Metamorph Hit Markup

The %s, %U, and %H codes can also execute Metamorph queries on the string parameter and markup the resulting hits. The m flag indicates that Metamorph hit markup should occur; the Metamorph query string (char *) is then taken to be the next parameter (before the normal string parameter to be searched and printed). The m flag and its sub-flags are only valid for %s, %U and %H codes, and must follow any standard printf() flags.

Following the m flag can be any of the following sub-flags. These must immediately follow the m flag, as some letters have other meanings elsewhere:

b for bold highlighting of hits
h for HREF highlighting (default)
n indicates that hits that overlap tags should not be truncated/moved
p for paragraph formatting: replace "\n\n" with "\n<P>\n\n" in output
c to continue hit count into next % code

The Metamorph query is opened with a default APICP pointer, or the one supplied by htpf_setapicp() if it was called earlier. Each hit found by the query has each of its sets' hits (not the overall hit) highlighted in the output.

The h flag sets HREF highlighting (the default). Each hit becomes an HREF that links to the next hit in the output, with the last hit pointing back to the first. In the output, the anchors for the hits are named hitN, where N is the hit number (starting with 1).

Hits can be bold highlighted in the output with the b flag; this surrounds them with <B> and </B> tags. b and h can be combined; the default if neither is given is HREF highlighting.

Normally, hits that are inside or overlap <> tags are truncated or moved to appear outside the tag in the output, so that the highlighting tags don't overlap them and muddle the HTML output. The n tag indicates that this truncation should not be done. (It is also not done for %H, since the tags in the string are escaped already.)

The p flag does paragraph formatting: double newlines in the string are replaced by "\n<P>\n\n" in the output.

The c flag indicates that the hit count should be continued for the next query. By default, the last hit in a %s, %U or %H string is linked back to the first hit. Therefore, each %-code query markup is self-contained: if multiple calls are made, the hit count (and resulting HREFs) will start over for each call, which may not be desired. If the c flag is given, the last hit in the string is linked to the "next" hit (N+1) instead of the first, and the next %-code query will start numbering hits at N+1 instead of 1. Thus, all but the last %s/%U/%H query printed by a program should have the c flag.

EXAMPLE

#include "cgi.h"

char  *Query   = "/yin /yang";
char  *Buffer1 = "This is a test.\nIs yin <\nyang?";
char  *Buffer2 = "Or is yang <\nyin?\nI can't know.";

...

{
  htpf("Results of query on %t:<HR>\n", time(NULL));
  htpf("%mcH\n", Query, Buffer1); /* the 'c' continues hit count */
  htpf("%mH\n", Query, Buffer2);
}

Output:

Results of query on Sat Oct  4 12:51:15 EST 1997:<HR>
This is a test.
Is <A NAME=hit1 HREF=#hit2>yin</A> &lt;
<A NAME=hit2 HREF=#hit3>yang</A>?
Or is <A NAME=hit3 HREF=#hit4>yang</A> &lt;
<A NAME=hit4 HREF=#hit1>yin</A>?
I can't know.

CAVEATS
The c flag to m queries makes the last HREF link to the next hit anchor, which doesn't exist yet; therefore it assumes the next query will have at least one hit, or else the link will point to a nonexistent anchor.