A parse mapping (data type XmParseMapping) is a fragment of multibyte text paired with a compound string component. When translating text into a compound string, using the XmParse functions, any occurrences of the parse mapping text will be translated into the compound string component with which it is paired in a parse mapping. Likewise, when converting a compound string back into regular text, each compound string component that matches a parse mapping will be translated into the corresponding text string. A parse table (data type XmParseTable) is nothing more than an ordered array of XmParseMappings.
Though the parse mapping is at heart nothing more than the text/compound string pairs, Motif stores each parse mapping with resources that indicate how the parsing is to proceed. Note that these are not widget resources, but the widget resource model provides a convenient way to specify and recall parse mapping instructions.
Following this model, an application uses the XtSetArg function to build a resource-style argument list to submit to the XmParseMappingCreate, XmParseMappingGetValues, or XmParseMappingSetValues in the same manner that would be used to create or change the resource values of some widget.
The parse mapping "resources" are outlined briefly below. For more information about the XmParseMapping data type and its resources, please see the Motif Programmer's Reference.
The Motif parsing mechanism allows for the execution of an arbitrarily complex parsing algorithm. If the simple substitution of compound string components for text strings is not powerful enough for a particular application, a programmer can define a parse procedure that will be invoked when certain text characters are read.
While parsing a text string, if an XmNpattern attached to a non-NULL XmNinvokeParseProc resource, matches part of the input string, the nominated parse procedure is invoked.
The XmNinvokeParseProc resource is a function of type XmParseProc, which is defined as follows:
XmIncludeStatus (*XmParseProc)(
XtPointer *
text_in_out,
XtPointer
text_end,
XmTextType
type,
XmStringTag
tag,
XmParseMapping
entry,
int
pattern_length,
XmString *
str_include,
XtPointer
call_data)
The input text is a pointer to the first byte of the pattern that was matched to trigger the call to the parse procedure. The parse procedure may use, modify, or remove as many bytes of the input string as it needs, as long as upon return the input text pointer is advanced to the following byte. It returns a compound string to be included in the compound string being constructed, as well as an XmIncludeStatus, corresponding to the parse mapping resource, indicating how the returned compound string should be handled.
The parse procedure returns an XmIncludeStatus indicating how str_include is to be included in the compound string being constructed. Following are the possible values:
Upon return, the function that invoked the parse procedure will continue looking for matching patterns from the position of the text pointer. If the parse procedure has not advanced the pointer, and the text and parse mappings also remain the same, the parse procedure will be called again, perhaps infinitely.
Two parse procedures are provided as part of Motif.
The XmeGetNextCharacter procedure consumes the byte the input pointer indicates, and the following byte, and returns a compound string component containing only the second byte. The effect is to copy the byte following the trigger byte directly into the output compound string, even if the normal parsing would not have done so. In other words, the trigger byte has served as an "escape" character. The XmeGetNextCharacter return value is XmINSERT, so parsing will continue normally from the same spot.
The other parse procedure included as a part of Motif is XmeGetDirection. This function simply returns an XmString component of type XmSTRING_COMPONENT_DIRECTION, whose value depends on the input text.
The following functions use a parse table to translate text into the compound string format and the reverse.
To use a parse table, send it and a companion text string to the XmStringParseText function. This function also accepts a pointer to data that may be passed to a parse procedure, if one exists. The function will walk through the input text string, copying characters from it into a compound string; when it finds a pattern (specified by XmNpattern in the parse mappings) to match a pattern in the input parse table, it will not copy the pattern, but write the corresponding compound string (indicated by XmNsubstitute in the parse mapping) to the output XmString.
In the event it is desirable to translate a compound string back into a text string, the XmStringUnparse function is provided. This provides the precise converse to the XmStringParseText function, stepping through the input compound string and substituting text patterns for XmString components that match the XmNsubstitute resources in the parse table. If there is no parse procedure nominated in the parse table, the XmStringUnparse function called on the output of the XmStringParseText function will equal the input of XmStringParseText. A compound string created with a parse table that includes a parse procedure will not be correctly translated into simple text by a call to XmStringUnparse.
The routines that create parse mappings allocate memory in which to store those mappings. It is the responsibility of the application, however, to free that memory when the mappings and tables are no longer needed. Use XmParseMappingFree and XmParseTableFree to free the memory for other uses.