'\" 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" "library call"
.SH "NAME"
\fBXmParseMapping\fR \(em Data type for a compound string parse mapping
.iX "XmParseMapping"
.iX "data types" "XmParseMapping"
.SH "SYNOPSIS"
.PP
.nf
#include <Xm/Xm\&.h>
.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