Changes for version 2.05 - 2026-11-10
- The values the widget keeps for Perl (on the nodes and leaves of blocks, marks, runs of tags, and as the instance data of blocks) live in data containers (tkTextData.h): the Perl value is to become one part of what is attached there, the rest holding, for example, switches for the operations that now follow one fixed rule (how the data of two merged tag runs is combined). All code goes through the operations of the header; the merge policy (N5, the first container present wins) is one function, TkTextDataMerge. Two representations, chosen when building: A (the default) is the Perl value itself and compiles to what the code did before; B ("ETEXT_DATA_ARRAYS=1 perl Makefile.PL", adds -DTK_TEXT_DATA_ARRAYS=1) is one pointer to a block of typed slots (a size, a capacity, an array of slots and an array of unsigned char type codes), of which the Perl value is the slot of type TK_TEXT_DATA_LANG. In both the field is one pointer wide. Undo records, undo atoms and the list of values to free carry whole containers. The Perl interface (block nodedata, mark data, tag data, block data, the [name, value] elements of block list, dump -values) reads and writes only the Perl value, as before: setting undef removes only that part. Limits of B, documented in the header: block list carries only the Perl values, so the other slots do not follow text re-inserted from a list, and the instance data of a block deleted and brought back by undo comes back from the list. A widget built with B has a hidden subcommand for the tests (_dataslot), and t/data-slots.t (skipped with A) checks that a slot survives drop, undo, redo and merges and that each container is freed once. Nothing changes for Perl code: the test suite gives the same results with A as 2.04, and passes with B. BUGS 22 and 23, found on the way: the instance data of a block is freed at once, not when the widget command ends, when "block data" replaces it and when an undo step that listed it is discarded. demo/etext.pl starts with its "#!/usr/bin/perl" line again: two stray lines, a copy of two lines of its body, came before it. Fixed: deleting a block of a type with -empty => 1 unlinked its segment and never freed it (72 bytes per block, since the 1997 code): t/stress.t lost 349 such pieces under valgrind, now none. t/leak.t watches the process size over 50000 such deletions. Fixed (BUGS 22): the instance data that "block data" replaces, or removes with undef, is freed when the widget command ends, as every other value, and no longer at once inside it: its DESTROY runs under the stopgap (commands that would modify the widget are refused), still before blockData returns. Fixed (BUGS 23): the undo of a deletion keeps the instance data of the blocks it deletes or dissolves as a record of its own (addressed by the block's head), as it keeps node and run values, and no longer as a copy in its block list, which now leaves instance data out. The undo gives the whole container back to the block it re-creates (with representation B, its other slots too), the redo takes it again, and a discarded step (edit reset, -maxundo, a new change after an undo) frees it when the widget command ends, under the stopgap. The same for the redo of an insertion, which re-inserts a block list. Setting block data now counts as setting a value for the snapshot an undoable deletion takes (BUGS 13). Fixed (BUGS 20): "tag names" at the head of a block reports the tags in effect there, as "tag ranges", "dump" and the searches do; it left out a tag that switches off inside the block. The display, the elide test and the mouse bindings keep the rule of 1997: such a tag does not style the block as a whole. The manual's "the behaviour of tags on the start of block is undefined" says so instead. Fixed: a tag with -elide on that started before a block and ended inside it hid the whole block and the rest of the line, text it does not cover included; the two loops of the display that skip hidden text now stop at a block inside which such a tag switches, and the block draws what the tag does not cover (BUGS 24). The manual ("Node values and editing") says what a deletion does to the last of a block's nodes directly above the leaves (and to its ancestors below the root): they hold the block's tail, so they are never deleted whole; when all their leaves are deleted they are joined to the node before them, and their values follow the rule for joined nodes (moved if that node has none, dropped otherwise). It said that such a node was deleted with its value. t/values.t pins it. Fixed (BUGS 18): the undo of a block insert whose range crossed nodes of an enclosing block gives the nodes back exactly, with their values. The block insert flattens the separators of its range (the leaves become children of the new block's single node), and the undo dissolved the block at level 0; the undo step now records the level of each separator in the range and of the one after it, and the undo sets each back to its level after dissolving the block (splitting or joining nodes; no text moves), before the values come back to the nodes at their addresses. The redo stays exact. The review's random undo/redo exactness check, which failed on 11 of 300 runs (all this bug), passes on all of them. t/demo.t hides its probe MainWindow instead of destroying it, and destroys it last: Perl/Tk's option-lookup cache goes stale when a MainWindow is destroyed, and the demo's MainWindow, created after it, crashed now and then (BUGS 21, under Wine). Fixed (BUGS 25): an -empty block that had moved to another line (a newline or a block split before it, block insert nesting it) kept pointing to its old line; "block at" on its head crashed. The B-tree check under "debug" looks for it. Fixed (BUGS 26): the undo of a deletion that dissolved a block freed a value set after the deletion on a leaf made of what was left of the block; it waits in the undo step now, and the redo gives it back. New option -valuecommand (BUGS 17): a callback told, before a command changes anything, which values the change will detach and where they are, while the widget is unchanged: $cb->($widget, $event, $kind, $where, $value, $cause). This first step covers setting and unsetting values (block nodedata, tag data, mark data, block data, mark unset), the runs that tag add, tag remove and tag delete drop or merge, the values an undo or a redo gives back ("restore") or moves aside, and those of undo steps thrown away ("discard", at the end of the command). A detach that was not foreseen is reported "late" after the change, and under "debug" the command fails. While the callback runs, the widget refuses the commands that would change it. t/valuecommand.t. The look-ahead of -valuecommand covers the structural changes too: deletions (leaves and nodes deleted or joined, as the manual's rules say, blocks deleted or dissolved with all their values and instance data, runs gone or merged, also around the heads and tails of dissolved blocks), block insert (the two parts of the cut leaves joined, nodes left without leaves), block trim, and the joins of nodes by which the undo of a block insert sets the separator levels back. t/valuecommand-random.t runs random commands (undo and redo included) on widgets with nested blocks and values everywhere, with "debug" on, and checks that every value detached was told before, at a place that names it during the call, that every value freed was told drop or discard, and that no late event occurs. The manual documents the option ("Telling the program: -valuecommand"). The stopgap of 2.04 is gone (BUGS 17): a DESTROY method run while the values a command dropped are freed may change the widget again. Such a change is an undo step of its own; the values it drops are freed in the same pass; a chain of such changes is refused 10 deep. Only the -valuecommand callback is refused changes (same list of commands as the stopgap had). A ready-made -valuecommand: -valuecommand => 'DETACH' calls the method DETACH of the widget (in eText.pm), which calls $value->DETACH($widget, $event, $kind, $where, $cause) for a value that is an object with such a method, and skips the others. The 10 rounds of values freed in which DESTROY methods may change the widget are a limit that the program can raise (the owner's design): when a change from a DESTROY method is about to be made at the limit, the widget calls $object->DESTROYmult($n, $limit) on the object whose DESTROY method makes it ($n counts the requests of the freeing pass from 1, $limit is the current limit, 10 at first), and a positive integer $more raises the limit to $limit + $more; anything else, no such method, a non-object, or a method that dies (a background error) and the change is refused as before, the error naming the limit. Asked is the innermost DESTROY running, so an object held inside a value answers for its own change. The limit and the count reset with each outermost command. t/destroymult.t. The manual says what happens when Perl code the widget calls dies ("When Perl code called by the widget dies"), and t/dying.t checks it: a DESTROY method that dies, or that lets a refused change leave it, gives Perl's "(in cleanup)" warning (only where warnings are on: the refusal comes from a Perl/Tk method compiled without "use warnings", so it is warned only under perl -w, and an eval in DESTROY catches it), and the values and the command go on; a -valuecommand callback, a DETACH method or DESTROYmult that dies is a background error and the command goes on. Each value is freed once in every case, and nothing the callback got is kept. Postponed (BUGS 27): -valuecommand tells before the command changes anything only for commands that make one change; those that make several (edit undo and redo, insert with tag lists, tag add and remove over several ranges, a deletion through the end of the text) tell before each of their changes, and a value an undo or a redo displaces is told just before it moves. The manual's -valuecommand section says so in a note marked "Postponed".
Modules
a Tk text widget with nestable "blocks" (editable formulas)