'\" t .\" ParMapA.sgm /main/10 1996/09/08 20:55:23 rws $ .de P! .fl \!!1 setgray .fl \\&.\" .fl \!!0 setgray .fl \" force out current output buffer \!!save /psv exch def currentpoint translate 0 0 moveto \!!/showpage{}def .fl \" prolog .sy sed -e 's/^/!/' \\$1\" bring in postscript file \!!psv restore . .de pF .ie \\*(f1 .ds f1 \\n(.f .el .ie \\*(f2 .ds f2 \\n(.f .el .ie \\*(f3 .ds f3 \\n(.f .el .ie \\*(f4 .ds f4 \\n(.f .el .tm ? font overflow .ft \\$1 .. .de fP .ie !\\*(f4 \{\ . ft \\*(f4 . ds f4\" ' br \} .el .ie !\\*(f3 \{\ . ft \\*(f3 . ds f3\" ' br \} .el .ie !\\*(f2 \{\ . ft \\*(f2 . ds f2\" ' br \} .el .ie !\\*(f1 \{\ . ft \\*(f1 . ds f1\" ' br \} .el .tm ? font underflow .. .ds f1\" .ds f2\" .ds f3\" .ds f4\" .ta 8n 16n 24n 32n 40n 48n 56n 64n 72n .TH "XmParseMapping" 3 .SH "NAME" \fBXmParseMapping\fR \(em Data type for a compound string parse mapping "XmParseMapping" "data types" "XmParseMapping" .SH "SYNOPSIS" .PP .nf #include .fi .SH "DESCRIPTION" .PP \fBXmParseMapping\fR is an opaque data type for a parse mapping used by \fBXmStringParseText\fP to create a compound string\&. A parse mapping contains a pattern to be matched in text being parsed to create a compound string\&. It also contains a compound string, or a function to be invoked to provide a compound string, to be included in the compound string being created whenever the pattern is matched\&. .PP An application uses a resource-style interface to specify components for an \fBXmParseMapping\fR\&. \fBXmParseMappingCreate\fP creates a parse mapping, using a resource-style argument list\&. \fBXmParseMappingGetValues\fP and \fBXmParseMappingSetValues\fP retrieve and set the components of a parse mapping\&. \fBXmParseMappingFree\fP recovers memory used by a parse mapping\&. \fBXmParseTable\fR is an array of \fBXmParseMapping\fR objects\&. .PP The \fBXmNinvokeParseProc\fP resource is a function of type \fBXmParseProc\fR, which is defined as follows: .PP .nf XmIncludeStatus (*XmParseProc) (\fItext_in_out, text_end, type, tag, entry, pattern_length, str_include, call_data\fP) XtPointer *\fItext_in_out\fP; XtPointer \fItext_end\fP; XmTextType \fItype\fP; XmStringTag \fItag\fP; XmParseMapping \fIentry\fP; int \fIpattern_length\fP; XmString *\fIstr_include\fP; XtPointer \fIcall_data\fP; .fi .PP A parse procedure provides an escape mechanism for arbitrarily complex parsing\&. This procedure is invoked when a pattern in the input text is matched with a pattern in a parse mapping whose \fBXmNincludeStatus\fP is \fBXmINVOKE\fP\&. .PP 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 consumes as many bytes of the input string as it needs and sets the input text pointer to the following byte\&. It returns a compound string to be included in the compound string being constructed, and it also returns an \fBXmIncludeStatus\fR indicating how the returned compound string should be handled\&. If the parse procedure does not set the input text pointer ahead by at least one byte, the parsing routine continues trying to match the input text with the patterns in the remaining parse mappings in the parse table\&. Otherwise, the parsing routine begins with the new input text pointer and tries to match the input text with patterns in the parse mappings starting at the beginning of the parse table\&. .IP "\fItext_in_out\fP" 10 Specifies the text being parsed\&. The value is a pointer to the first byte of text matching the pattern that triggered the call to the parse procedure\&. When the parse procedure returns, this argument is set to the position in the text where parsing should resume\(emthat is, to the byte following the last character parsed by the parse procedure\&. .IP "\fItext_end\fP" 10 Specifies a pointer to the end of the \fItext_in_out\fP string\&. If \fItext_end\fP is NULL, the string is scanned until a NULL character is found\&. Otherwise, the string is scanned up to but not including the character whose address is \fItext_end\fP\&. .IP "\fItype\fP" 10 Specifies the type of text and the tag type\&. If a locale tag should be created, \fItype\fP has a value of either \fBXmMULTIBYTE_TEXT\fP or \fBXmWIDECHAR_TEXT\fP\&. If a charset should be created, \fItype\fP has a value of \fBXmCHARSET_TEXT\fP\&. .IP "\fItag\fP" 10 Specifies the tag to be used in creating the result\&. The type of string tag created (charset or locale) depends on the text type and the passed in \fItag\fP value\&. If the \fItag\fP value is NULL and if \fItype\fP indicates that a charset string tag should be created, the string tag has the value that is the result of mapping \fBXmSTRING_DEFAULT_CHARSET\fP\&. If \fItype\fP indicates a locale string tag, the string tag has the value \fB_MOTIF_DEFAULT_LOCALE\fP\&. .IP "\fIentry\fP" 10 Specifies the parse mapping that triggered the call to the parse procedure\&. .IP "\fIpattern_length\fP" 10 Specifies the number of bytes in the input text, following \fItext_in_out\fP, that constitute the matched pattern\&. .IP "\fIstr_include\fP" 10 Specifies a pointer to a compound string\&. The parse procedure creates a compound string to be included in the compound string being constructed\&. The parse procedure then returns the compound string in this argument\&. .IP "\fIcall_data\fP" 10 Specifies data passed by the application to the parsing routine\&. .PP The parse procedure returns an \fBXmIncludeStatus\fR indicating how \fIstr_include\fP is to be included in the compound string being constructed\&. Following are the possible values: .IP "\fBXmINSERT\fP" 10 Concatenate the result to the compound string being constructed and continue parsing\&. .IP "\fBXmTERMINATE\fP" 10 Concatenate the result to the compound string being constructed and terminate parsing\&. .SS "New Resources" .PP The following table defines a set of resources used by the programmer to specify data\&. The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fBXmParseMappingSetValues\fP (S), retrieved by using \fBXmParseMappingGetValues\fP (G), or is not applicable (N/A)\&. .PP .TS tab() box; c s s s s l| l| l| l| l. \fBXmParseMapping Resource Set\fP \fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP _____ XmNclientDataXtPointerNULLCSG _____ XmNincludeStatusXmIncludeStatusXmINSERTCSG _____ XmNinvokeParseProcXmParseProcNULLCSG _____ XmNpatternXtPointerNULLCSG _____ XmNpatternTypeXmTextTypeXmCHARSET_TEXTCSG _____ XmNsubstituteXmStringNULLCSG _____ .TE .IP "\fBXmNclientData\fP" 10 Specifies data to be used by the parse procedure\&. .IP "\fBXmNincludeStatus\fP" 10 Specifies how the result of the mapping is to be included in the compound string being constructed\&. Unless the value is \fBXmINVOKE\fP, the result of the mapping is the value of \fBXmNsubstitute\fP\&. Following are the possible values for \fBXmNincludeStatus\fP: .RS .IP "\fBXmINSERT\fP" 10 Concatenate the result to the compound string being constructed and continue parsing\&. .IP "\fBXmINVOKE\fP" 10 Invoke the \fBXmNinvokeParseProc\fP on the text being parsed and use the returned compound string instead of \fBXmNsubstitute\fP as the result to be inserted into the compound string being constructed\&. The include status returned by the parse procedure (\fBXmINSERT\fP or \fBXmTERMINATE\fP) determines how the returned compound string is included\&. .IP "\fBXmTERMINATE\fP" 10 Concatenate the result to the compound string being constructed and terminate parsing\&. .RE .IP "\fBXmNinvokeParseProc\fP" 10 Specifies the parse procedure to be invoked when \fBXmNincludeStatus\fP is \fBXmINVOKE\fP\&. .IP "\fBXmNpattern\fP" 10 Specifies a pattern to be matched in the text being parsed\&. This is a maximum of one character\&. .IP "\fBXmNpatternType\fP" 10 Specifies the type of the pattern that is the value of \fBXmNpattern\fP\&. Following are the possible values: .RS .IP " \(bu" 6 \fBXmCHARSET_TEXT\fP .IP " \(bu" 6 \fBXmMULTIBYTE_TEXT\fP .IP " \(bu" 6 \fBXmWIDECHAR_TEXT\fP .RE .IP "\fBXmNsubstitute\fP" 10 Specifies the compound string to be included in the compound string being constructed when \fBXmNincludeStatus\fP is \fBXmINSERT\fP or \fBXmTERMINATE\fP\&. .SH "RELATED" .PP \fBXmParseMappingCreate\fP(3), \fBXmParseMappingFree\fP(3), \fBXmParseMappingGetValues\fP(3), \fBXmParseMappingSetValues\fP(3), \fBXmParseTable\fP(3), and \fBXmString\fP(3)\&. .\" created by instant / docbook-to-man, Sun 22 Dec 1996, 20:27