Additional Command 'inspect'

pathName inspect ?switches?

Return the content of the text widget, including the text and optionally information about tags, embedded windows, and embedded images. The information is returned in the following format (notated in EBNF; BEG denotes the start of a list, end END denotes the end of the list; white spaces will not be taken into consideration):

Inspect       = BEG , ( Setup )? , ( Configure )? , ( Segment )+ , END ;
Setup         = BEG , "setup" , PathName , TextOptions , END ;
Configure     = BEG , "configure" , TagName , ( BEG , TagOptions, END )? , END ;
Bindings      = BEG , "bind", TagName , ( BEG , Script , END ) , END ;
Segment       = BEG , ( ( Content , TagInfo ) | Mark | Elide | Binding ) , END ;
Content       = Text | Hyphen | Break | EmbImage | EmbWindow ;
Text          = "text" , BEG , ( Character )+ , END ;
Hyphen        = "hyphen" ;
EmbImage      = "image" , ImageOptions ;
EmbWindow     = "window" , WindowOptions ;
Mark          = Gravity , MarkName ;
Gravity       = "left" | "right" ;
Elide         = "elide" , ( "on" | "off" ) ;
TagInfo       = Tags , ( Tags )? ;
Tags          = BEG , ( TagName )* , END ;
Character     = ? Any character (UTF-8), but no newline ? ;
Newline       = ? The newline character ? ;
TextOptions   = ? See STANDARD OPTIONS and WIDGET-SPECIFIC OPTIONS ?
TagOptions    = ? See TAGS ? ;
ImageOptions  = ? See EMBEDDED IMAGES ? ;
WindowOptions = ? See EMBEDDED WINDOWS ? ;
PathName      = ? Any valid widget pathname ? ;
TagName       = ? Any tag name ? ;
MarkName      = ? Any mark name ? ;

We will also provide an informal description of the items; note that the optional tagList will be provided only if option -nested is specified:

{"setup" pathName configurationList}
{"configure" tagName ?configurationList?}
{"bind" tagName event script}
{"text" content tagList ?tagList?}
{"break" tagList ?tagList?}
{"hyphen" tagList ?tagList?}
{"image" imageOptions tagList ?tagList?}
{"window" windowOptions tagList ?tagList?}
{"left" markName}
{"right" markName}
{"elide" "on"|"off"}

One or more of the following switches (or abbreviations thereof) may be specified to control the extraction:

-all
Return information about all elements: text (characters and soft hyphens), tags, images, and windows. This is the default, and includes the following switches: -text, -image, -window, -tag, -configurations.

-bindings
Include all tag bindings into the result.

-chars
Include information about characters and soft hyphens in the dump results. The content of this segment is the text up to the next segment. The segmentation of text depends on the tagging information, any change in tagging is starting a new segment.

-configurations
Include all the tag configurations.

-discardselection
This option makes sense only if also option -tag (or -all) is specified. With this option the selection tag sel will be discarded from the result.

-displaychars
If this option is given, then only those characters and soft hyphens which are not elided will be included into the result of the text element.

-displaytext
If this option is given, then only those characters which are not elided will be included into the result of the text element. Note that soft hyphens (Unicode point U+00AD) do not belong to this result.

-dontresolvecolors
Do not system resolve color names (this is affecting the content of -setup, and -configurations). Resolving system color names is required for portability, but in case of system dependent use (if all system color names will be resolvable) it is not required. Per default system color names will be resolved.

-dontresolvefonts
Do not resolve font names (this is affecting the content of -setup, and -configurations). Resolving font names is required for portability, but in case of private use (if all font names will be resolvable) it is not required. Per default font names will be resolved.

-elide
The result will also include information about elided regions. It is for information only – better visibility of elided text – the load command will ignore these elements.

-image
Include information about images in the result. The content of the image is a list containing the image options.

-insertmark
Include information about the "insert" mark in the dump results. Without this option this mark will not be printed.

-mark
Include information about marks in the dump results. Depending on the gravity the type of this segment is either left or right. The segment content is the name of the mark. The special marks insert and current will be discarded (but see option -insertmark), and generated marks will also be discarded.

-nested
This option will only be regarded in conjunction with switch -tag, see description of switch -tag below.

-setup
Include the pathname of the widget, and a list of configuration options.

-tag
Include information about tags in the result. If additionally option -nested is specified, then two tag sets will be provided: firstly all the tags starting with this content, and secondly all the tags ending after this content (similar to the tagon, tagoff ranges in the dump format). Without option -nested (this is the default) only one list will be provided, namely all the tags associated to this segment content. The tag list will be written in decreasing order, sorted by the priority of the tag.

-text
Include information about text (characters) in the dump result. The content of this segment is the text up to the next segment. The segmentation of text depends on the tagging information, any change in tagging is starting a new segment. Note that soft hyphens (Unicode point U+00AD) do not belong to this result.

-window
Include information about embedded windows in the result. The content of a window is a list containing the window options. If a window has not been created yet, then it will not appear in the result of command inspect.

The result of this command can be used for loading a widget with a snapshot (see command load).

Contrary to the dump command a quite simple, flat format will be returned. This is the appropriate format for doing changes on the result, and then load back with the changes (see command load). It is also the appropriate format for transferring, and analyzing the widget content. Moreover it allows to save and restore snap-shots.