8. Text modification commands

The commands described in this chapter operate on the textual representation of the document rather than on the SGML/XML structure. Depending on the command, markup is either ignored or treated as a character sequence by these commands.

Text modification commands

insert index ?tagList chars tagList?
	inserts chars at location index, optionally assigning tag annotations taglist to the characters that have been inserted.
delete index1 ?index2?
	deletes the characters between index1 and index2 from the widget. If index2 has been omitted, the single character at index1 is deleted.
get index1 ?index2?
	return the text corresponding to the characters between index1 and index2. If index2 has been omitted, the text corresponding to the single character at index1 is returned.
iget index1 ?index2?
	return the index-space equivalent of the characters between index1 and index2. If index2 has been omitted, the equivalent of the single character at index1 is returned.
search ?switches? pattern index ?stopindex?
	searches the widget starting at index for a range of characters that matches pattern.
matches
	Returns a list with the matches for the subexpressions in the last regular expression search.
dump ?switches? index1 ?index2?
	Returns the contents of the sgml widget at index1 up to, but not including index2. The exact form of the result is determined by switches.
edump ?switches? index1 ?index2?
	This is an extended version of the dump command. Returns the contents of the sgml widget at index1 up to, but not including index2. The exact form of the result is determined by switches.

The individual commands are described in more detail in the following sections.

8.1 Insert

The insert widget command inserts a sequence of characters into the sgml widget. The location where the insertion occurs is specified by an index which can be given in any of the forms described in section . The general form of the command is:

pathName insert index ?tagList chars tagList?

If there is a single chars argument and no tagList, then the new text will receive any tags that are present on both the character before and the character after the insertion point; if a tag is present on only one of these characters then it will not be applied to the new text.

If tagList is specified then it consists of a list of tag annotation names; the new characters will receive all of the tag annotations in this list and no others, regardless of the tags present around the insertion point. If multiple chars - tagList argument pairs are present, they produce the same effect as if a separate insert widget command had been issued for each pair, in order. The last tagList argument may be omitted.

It is not possible to insert data before or after the document element.

The text to be inserted can contain SGML (or XML) markup which is interpreted according to the location specified by index. If the index is within an element with mixed or element content, any sgml markup in the text must be allowed at this index. More important, the inserted text itself must be well-formed in the sense that tags must be properly nested.

If the insertion of the text leads to the creation of new elements and an -insertnotify callback has been installed, the callback function is invoked with handles to all elements that have been inserted.

8.2 Delete

The pathName delete widget command deletes a range of characters from the text:

pathName delete index1 ?index2?

If both index1 and index2 are specified, then delete all the characters starting with the one given by index1 and stopping just before index2 (i.e. the character at index2 is not deleted). If index2 doesn't specify a position later in the text than index1 then no characters are deleted. If index2 isn't specified then the single character at index1 is deleted. It is not allowed to delete characters in a way that would leave the text without a newline as the last character. The command returns an empty string.

The deleted text can contain markup. If any markup lies in the range of the region defined by index1 and index2, the markup must be properly nested for the command to succeed. The delete widget command will refuse to delete any of the text between index1 and index2 if this constraint is violated.

If any SGML elements have been deleted by the delete widget command and a -deletenotifycmd callback has been installed, the notification callback will be invoked with handles to all elements that will be deleted immediately before these elements are removed from the widget. If the callback function returns an error, the delete process is canceled and no text is deleted.

See chapter  for details about notification callbacks.

8.3 Get and Iget

The pathName get widget command returns the textual representation of a range of text specified by one or two indices. The result of the get command is a string where all markup icons have been replaced by the corresponding sgml markup in textual form.

Both the get and iget commands return a range of characters from the text. The return value will be all the characters in the text starting with the one whose index is index1 and ending just before the one whose index is index2 (the character at index2 will not be returned). If index2 is omitted then the single character at index1 is returned. If there are no characters in the specified range (e.g. index1 is past the end of the text or index2 is less than or equal to index1 ) then an empty string is returned.

The difference of get and iget is that get expands all sgml markup to its textual form while iget replaces any markup in the returned text with a single character. The result of iget can be used for index calculations because it represents the handling of markup by the sgml widget.

If the specified range contains embedded windows or images, no information about them is included in the result of the get command.

8.4 Search

The search command searches the widget for a range of characters that match a specified pattern. The search process can be modified by providing switches to the search command and by defining the end of the range that should be searched. The general form of the command is

pathName search ?switches? pattern index1 ?stopindex?

If a match is found, the index of the first character in the match is returned as result; otherwise an empty string is returned. One or more of the following switches (or abbreviations thereof) may be specified to control the search:

• -forwards

  The search will proceed forward through the text, finding the first matching range starting at or after the position given by index. This is the default.

• -backwards

  The search will proceed backward through the text, finding the matching range closest to index whose first character is before index .

• -exact

  Use exact matching: the characters in the matching range must be identical to those in pattern. This is the default.

• -regexp

  Treat pattern as a regular expression and match it against the text using the rules for regular expressions (see the description of the Tcl regexp command for details).

• -nocase

  Ignore case differences between the pattern and the text.

• -withtags

  Include the textual representation of sgml tags in the search. By default, tags and entity names will be ignored.

• -count varName

  The argument following -count gives the name of a variable; if a match is found, the number of characters in the matching range will be stored in the variable.

• -

  This switch has no effect except to terminate the list of switches: the next argument will be treated as pattern even if it starts with -.

The matching range must be entirely within a single line of text. For regular expression matching the newlines are removed from the ends of the lines before matching: use the $ feature in regular expressions to match the end of a line. For exact matching the newlines are retained. If stopIndex is specified, the search stops at that index: for forward searches, no match at or after stopIndex will be considered; for backward searches, no match earlier in the text than stopIndex will be considered. If stopIndex is omitted, the entire text will be searched: when the beginning or end of the text is reached, the search continues at the other end until the starting location is reached again; if stopIndex is specified, no wrap-around will occur.

If -withtags has been specified and the match included only parts of a markup tag, the index and the length of the match are adjusted so that the complete tag is included in the match.

After searching with a regular expression, the matches for the subexpressions can be retrieved with the pcrmmatches widget command. The command has the general form

pathName matches

The command returns a list of matches where the nth element in the list corresponds to the nth subexpression in the regular expression. The first element (with the index of 0) contains the match for the complete regular expression.

8.5 Dump and Edump

The dump and edump widget command return the contents of an sgml widget in a form close to the internal representation of the SGML data in the widget. The pcrmdump command has been designed for compatibility with the Tk text widget while the pcrmedump command is an extended version of pcrmdump.

New applictations are encouraged to use pcrmedump instead of pcrmdump which is only retained for compatibility with existing applications.

The general form of the pcrmedump command is

pathName edump ?switches? index1 ?index2?

The command returns the contents of the widget from index1 up to, but not including index2. If index2 is not specified, the if defaults to one character past index1. The information is returned as a Tcl list in the following format:

key1 value1 index1 key2 value2 index2 ...

The possible keys and the meaning of the corresponding values are described in the table below:

Key	Value
text	This part of the result corresponds to character data which starts at the corresponding index.
mark	This corresponds to a mark that has been set at the location given by index. The value is the name of the name of the mark at this location.
tagon	A tag annotation is turned on at this location. The value is the name of the tag starting at this index. The tagged region starting at this index continues up to the next ocurrence of a tagoff key with the corresponding tag annotation name. Depending on the values of the index arguments of the dump command, the result does not necessarily contain the end of the tagged region.
tagoff	A tag annotation is turned off at this location. The value is the name of the tag annotation ending at this index.
window	The sgml widget conatins an embedded window at this index. The value is the Tk pathname of the window, unless the window has not been create yet. In this case, an empty string is returned and the window must be queried by its index position for more information.
space	Ignorable white-space
image	The name of an embedded image at this index.
cref	The numerical value of a character reference.
elstag	A handle for an SGML element that begins here.
eletag	A handle for an SGML element that ends here.
pistag	A handle for a processing instruction at this index.
pietag	A handle for a processing instruction that ends at this index.
cmstag	A handle for a comment at this index.
cmetag	A handle for a comment that ends at this index.
msstag	A handle for a marked section that begins at this location.
msetag	A handle for a marked section that ends at this location.
re	A record end.
entity	The value is the name of an entity that is referenced at this index.
testag	The value is the name of an expanded text entity that starts at this location.
teetag	The value is the name of an expanded text entity that ands at this location.
undo	The location specified by index is marked for an undo operation. The value field is an empty string.

Additional switches control the exact behavior of the dump command. The following switches are supported:

• -all

  Return all available information for the specified range.

• -command command

  Instead of returning the information as the result of the dump operation, invoke the command on each result within the range. The command has three arguments appended to it before it is evaluated: the key, value, and index.

• -mark

  Include information about marks in the dump results.

• -tag

  Include information about tag transitions in the dump results. Tag information is returned as tagon and tagoff elements that indicate the begin and end of each range of each tag, respectively.

• -text

  Include information about text in the dump results. The value is the text up to the next element or the end of range indicated by index2. A text element does not span newlines. A multi-line block of text that contains no marks or tag transitions will still be dumped as a set of text segments that each end with a newline. The newline is part of the value.

• -window

  Include information about embedded windows in the dump results.

• -window

  Include information about visible data (text, image annotations, embedded windows, and markup) in the dump results.

• -entity

  Include information about entity references in the dump results.

• -markup

  Include markup information in the dump results.

The general form of the pcrmdump command is

pathName dump ?switches? index1 ?index2?

The command returns the contents of the widget from index1 up to, but not including index2. If index2 is not specified, the if defaults to one character past index1. The information is returned as a Tcl list in the following format:

key1 value1 index1 key2 value2 index2 ...

The possible keys and the meaning of the corresponding values are described in the table below:

Key	Value
text	This part of the result corresponds to character data which starts at the corresponding index.
mark	This corresponds to a mark that has been set at the location given by index. The value is the name of the name of the mark at this location.
tagon	A tag annotation is turned on at this location. The value is the name of the tag starting at this index. The tagged region starting at this index continues up to the next occurrence of a tagoff key with the corresponding tag annotation name. Depending on the values of the index arguments of the dump command, the result does not necessarily contain the end of the tagged region.
tagoff	A tag annotation is turned off at this location. The value is the name of the tag annotation ending at this index.
window	The sgml widget contains an embedded window at this index. The value is the Tk pathname of the window, unless the window has not been create yet. In this case, an empty string is returned and the window must be queried by its index position for more information.
image	The name of an embedded image at this index.
sgmlstag	The start tag of an SGML element. The value is the content of the markup icon
sgmletag	The end tag of an SGML element.
pi	The start or end tag for a processing instruction.
ms	A marked section start or end tag.
re	A record end.
entity	The value is the name of an entity that is referenced at this index.
textentity	A text entity start or end tag.
undo	The location specified by index is marked for an undo operation. The value field is an empty string.

The additional switches are same as for the pcrmedump command.

The dump command is potentially useful for implementing interactive behavior depending on the exact location where an event occurred within an sgml widget.