infommapi - Metamorph API hit information

SYNOPSIS

#include <stdio.h>
#include "api3.h"

int     infommapi(mm, index, what, where, size)
MMAPI  *mm;
int     index;
char  **what;
char  **where;
int    *size;

DESCRIPTION
After a hit has been located by the getmmapi() function, the calling program may get information about objects contained within the hit by passing the MMAPI * to the infommapi() function. This call can provide the following information:

Location and length of the entire hit.
Location and length of the start delimiter.
Location and length of the end delimiter.
For each set in the search that was matched:
- The query set searched for and located.
- The location of the set item.
- The length of the set item.

The idea behind infommapi() is to provide the caller with a structured method for obtaining information about a hit that was located with the getmmapi() call. The index parameter and the return code are used to "walk" through the items that were located. Information about each item is placed into the variables pointed to by the what, where and size parameters. A return value of -1 indicates a usage error, 0 indicates that the index is out of range, and 1 indicates that the index was in range and the data is valid.

Index values and what they return:

infommapi(mm, 0, &what, &where, &size)
what : Will be set to the query that was passed to the openmmapi()
       call.
where: Will point to the location of the hit within the buffer being
       searched.
size : Will be the overall length in bytes of the located hit.

infommapi(mm, 1, &what, &where, &size)
what : Will be set to the start delimiter expression in use.
where: Will point to the location of start delimiter.
size : Will be the overall length in bytes of the located delimiter.
       size will be 0 and where will be (char *)NULL if the hit is at
       the beginning of the buffer or immediately after the previous
       hit.

infommapi(mm, 2, &what, &where, &size)
what : Will be set to the end delimiter expression in use.
where: Will point to the location of end delimiter.
size : Will be the overall length in bytes of the located delimiter.
       size will be 0 and where will be (char *)NULL if the hit is at
       the end of the search buffer and no end delimiter was found in
       the buffer.

infommapi(mm, [3...n], &what, &where, &size)
what : Will point to the first "set" being searched for;

set type    what points to
--------    --------------------------
REX         A regular expression
NPM         The npm query expression
PPM         The root word of the list of words
XPM         The "approximate" string

where: Will point to the buffer location of the set-element.
size : Will be the overall length in bytes of the located set-element.

EXAMPLE

{
 MMAPI  *mm;
 char   *what, *where;
 int    size, index;

 ...

  for (index = 0;
       infommapi(mm, index, &what, &where, &size) == 1;
       index++)
      {
       switch (index)
           {
            case 0 :
               printf("The Query: %s\n", what);
               printf("The hit  :");
               for( ; size > 0; size--, where++) putchar(*where);
               putchar('\n');
               break;
            case 1 :
               printf("The start delimiter expression: %s\n", what);
               printf("The start delimiter located   :");
               for( ; size > 0; size--, where++) putchar(*where);
               putchar('\n');
               break;
            case 2 :
               printf("The end delimiter expression: %s\n", what);
               printf("The end delimiter located   :");
               for( ; size > 0; size--, where++) putchar(*where);
               putchar('\n');
               break;
            default:
               printf("set %d expression: %s\n", index - 2, what);
               printf("The set located  :");
               for( ; size > 0; size--, where++) putchar(*where);
               putchar('\n');
               break;
           }
      }
 ...

}