NAME

       XmParseMapping  —  Data  type  for  a compound string parse mapping "XmParseMapping" "data
       types" "XmParseMapping"

SYNOPSIS

       #include <Xm/Xm.h>

DESCRIPTION

       XmParseMapping is an opaque data type for a parse mapping  used  by  XmStringParseText  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.

       An  application  uses  a  resource-style  interface   to   specify   components   for   an
       XmParseMapping.   XmParseMappingCreate  creates  a  parse  mapping, using a resource-style
       argument list.  XmParseMappingGetValues and XmParseMappingSetValues retrieve and  set  the
       components  of  a  parse  mapping.   XmParseMappingFree  recovers  memory  used by a parse
       mapping.  XmParseTable is an array of XmParseMapping objects.

       The XmNinvokeParseProc resource is a function of type XmParseProc,  which  is  defined  as
       follows:

       XmIncludeStatus (*XmParseProc) (text_in_out, text_end, type, tag, entry, pattern_length,
       str_include, call_data)
               XtPointer *text_in_out;
               XtPointer text_end;
               XmTextType type;
               XmStringTag tag;
               XmParseMapping entry;
               int pattern_length;
               XmString *str_include;
               XtPointer call_data;

       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 XmNincludeStatus is XmINVOKE.

       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 XmIncludeStatus 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.

       text_in_out
                 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—that is, to the byte following the last character
                 parsed by the parse procedure.

       text_end  Specifies a pointer to the end of the text_in_out string.  If text_end 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 text_end.

       type      Specifies the type of text and the tag type.  If a locale tag should be created,
                 type  has  a  value of either XmMULTIBYTE_TEXT or XmWIDECHAR_TEXT.  If a charset
                 should be created, type has a value of XmCHARSET_TEXT.

       tag       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 tag
                 value.  If the tag value is NULL and if type indicates that a charset string tag
                 should  be  created,  the string tag has the value that is the result of mapping
                 XmSTRING_DEFAULT_CHARSET.  If type indicates a locale string tag, the string tag
                 has the value _MOTIF_DEFAULT_LOCALE.

       entry     Specifies the parse mapping that triggered the call to the parse procedure.

       pattern_length
                 Specifies  the  number  of  bytes in the input text, following text_in_out, that
                 constitute the matched pattern.

       str_include
                 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.

       call_data Specifies data passed by the application to the parsing routine.

       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:

       XmINSERT  Concatenate  the  result  to  the compound string being constructed and continue
                 parsing.

       XmTERMINATE
                 Concatenate the result to the compound string being  constructed  and  terminate
                 parsing.

   New Resources
       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 XmParseMappingSetValues (S), retrieved by using XmParseMappingGetValues
       (G), or is not applicable (N/A).

       ┌───────────────────────────────────────────────────────────────────────┐
--

RELATED

       XmParseMappingCreate(3),        XmParseMappingFree(3),         XmParseMappingGetValues(3),
       XmParseMappingSetValues(3), XmParseTable(3), and XmString(3).

                                                                                XmParseMapping(3)