10. Index commands

Index-related widget commands

index index
	Returns a normalized form of index.
compare index1 op index2
	Returns a boolean value indicating if the relation op holds for index1 and index2.
adjustrange index1 index2
	Returns a pair of indices derived from index1 and index2 that ensures proper nesting.
location index line column
	Returns an index corresponding to the location specified by line and column in the external representation of the document.
location get index
	Converts index to a corresponding location in the external representation of the document.

10.1 Normalizing indices

Indices can be specified in several ways as described in section while a normalized index has the form line.char. The index widget command accepts any form of index and returns the normalized form of the index. It has the general form

pathName index index

The command returns the position corresponding to index in the form line.char where line is the line number and char is the character number. Index may have any of the forms described in section .

10.2 Comparing indices

Given two indices, they may refer to the same character in a document of the character referred to by the first index may occur before or after the character referred to by the second index. The compare widget command is used to test these relations and returns a boolean value that indicates whether a specifed relation is true for a pair of given indices. The command has the following general form:

pathName compare index1 op index2

The command compares the indices given by index1 and index2 according to the relational operator given by op, and returns 1 if the relationship is satisfied and 0 if it isn't. Op must be one of the operators described in the following table.

Operator	Meaning
<	Less than
<=	Less than or equal to
==	Equal to
>=	Greater than or equal to
>	Greater than
!=	Not equal to

If op is == then 1 is returned if the two indices refer to the same character, if op is < then 1 is returned if index1 refers to an earlier character in the text than index2, and so on.

10.3 Adjusting index ranges

A pair of indices may describe any region of a document. Markup in this region is not necessarily balanced (i.e. the region may contain stray tags where the corresponding start or end tags are outside of the range between the two indices). The adjustrange widget command accepts a pair of indices and expands them so that all enclosed markup is properly balanced. The command has the following general form:

pathName adjustrange index1 index2

The command returns a list of two indices derived from index1 and index2. The elements of the returned list describe a region of text in the sgml widget that has been expanded in such a way that elements (and other markup tags) in this region are properly nested.

The range returned by the adjustrange command is never smaller than the range given by index1 and index2. In other words: The first element of the returned list is an index that refers to the character at index1 or earlier; the second element in the returned list refers to a character in the text at index2 or later.

10.4 Mapping to and from external locations

An index in the sgml widget is not necessarily equal to the line and column of the corresponding location in the external representation of the document. For example, an SGML document may contain the DTD (or a part of it) at the beginning of the document so that index 1.0 (the location of the document element's start tag in the sgml widget) will not be equal to the occurence of the document elements start tag in the external file (where it occurs somewhere after the document prolog).

To simplify the mapping from the external document location to the indices in the sgml widget, the sgml widget records occurrence information about the documents markup when the document is loaded and updates this information when the document is saved. Based on this information, it is possible to to map an external location in the document to a widget index and vice versa.

The location index command accepts an specification of the external locationb and returns the corresponding widget index. It has the general form

pathName location index1 line column

The command returns a widget index that correspond to the location specified by line and column in the external representation of the document. For better integration with other SGML/XML processing software, column numbers for external locations start with 1 (as opposed to the column numbering scheme of the sgml widget where columns are numbered from 0). For example, the following procedure would set the insertion cursor to a location returned by an external SGML/XML processing software and scroll that position into view:

{}
  proc showLocation { line column } {
    set idx [ .s location index $line $column  ]
    .s mark set insert $idx
    .s see insert
  }

The location get widget command returns the external location for a given index in the sgml widget. The general form of the command is

pathName location get index

The command returns a list of two elements. The first element of this list is the line number corresponding to the index argument. The second element is the column number.