fmtcp - set fmt control parameters

SYNOPSIS

<fmtcp $setting [args ...]>

DESCRIPTION
fmtcp controls various facets of fmt and variable printing behavior. The possible settings are:

• query $fmt $query Sets the Metamorph query to use for automatic hit markup (highlighting of user query terms in the document). Takes a fmt-style format for Metamorph markup and the query as arguments, e.g. <fmtcp query "%mIH" $query>. After this call, the <mm> and </mm> functions (here) may be used to enable the automatic markup of all variables printed within such a <mm> block, using the given query and format.

  For marking up just a single variable, it may be easier to call <fmt> directly (here).

• sandblast [noesc] $search $replace Sets the search and replace list to use for automatic search and replace. Takes a list of REX search expressions and a list of corresponding plain-text replacement strings, like sandr (here) with the difference that no characters in the replace string are special. After this call, the <sb> and </sb> functions (here) may be used to enable the automatic search and replace of all variables printed, using these expressions.

  If the optional noesc flag is given, then HTML escapement of variables after replacement is not done in HTML mode, as it would normally be done. In non-HTML content types noesc has no effect.

  sandblast was added in version 2.1.899870000 19980708.

• sandcall [noesc] $search $func Like sandblast, but with callback functions instead of replace strings. When a REX expression in the $search list matches, the corresponding Vortex script function named in $func is called, instead of printing a replacement string. The function can have the following parameters which will be set:

  • hit The string matching the REX expression.

  • expn The index of the expression which matched, starting with 0 for the first expression in $search.

  • tag The name of the first HTML tag recognized in the hit.

  • attrs The attributes of the first HTML tag in the hit.

  • vals The corresponding values of the attributes of the first tag in the hit.

  • offset The offset of the hit from the start of the buffer. Added in version 7.07.1584226000 20200314; should be initialized in function declaration for back-compatibility with earlier Texis versions.

  • length The byte length of the hit. Added in version 7.07.1584226000 20200314; should be initialized in function declaration for back-compatibility with earlier Texis versions.

  The tag, attrs and vals parameters are useful for on-the-fly parsing of HTML embedded within some source data. If noesc is given, then HTML escapement of the non-hit portions of variables is not done in HTML mode, as would be the default.

  sandcall was added in version 2.6.918680000 19990210.

  Note that in version 7.06.1518116000 20180208 and later, callback parameter initialization became stricter; see the discussion for <pagelinks> callbacks (here) for details.

  Note that in version 7.07.1584374000 20200316 and later, the \<nomatch\> escape (here) is supported for expressions, which may be useful when writing parsers with sandcall.

• promoteints on|off Controls whether to automatically promote integer format codes in fmt and strfmt to the largest type available, i.e. implicitly use the w flag. With this on, large integers can be printed without truncation without having to specify the l, ll, or w flags in the format code. On by default. Added in version 3.01.984500000 20010312.

• defaults Restores default settings; also clears sandblast/sandcall settings. Added in version 5.01.1223065064 20081003.

• querystyle $style|default Sets the inline style for highlighting the entire query, when a delimiter (e.g. w/sent) is used. Setting default restores the default, which is bold black text on light grey. If an empty string is set, or no delimiter is used in the query, or the delimiter is the whole document, no overall-query style highlighting is done (but see highlightwithindoc). Inline styles are used with the I highlighting subflag of <fmt>. Added in version 6.

• querysetstyles [$styles ...]|[default] Sets the inline styles for highlighting individual sets (terms) in a query. Setting default restores the default, which is white or black text on 10 different background colors. If the number of styles set is less than querysetcyclenum, the last style will be re-used for later terms. If an empty string is set, no per-set style highlighting is done. Inline styles are used with the I highlighting subflag of <fmt>. Added in version 6.

• queryclass $class|default Sets the class name for highlighting the entire query, when a delimiter (e.g. w/sent) is used. Setting default restores the default, which is "query". If an empty string is set, or no delimiter is used in the query, or the delimiter is the whole document, no overall-query class highlighting is done (but see highlightwithindoc). Note that it is up to the programmer to supply a stylesheet definition for the query class and any other set classes used; see <fmtinfo> (here). Inline classes are used with the C highlighting subflag of <fmt>. Added in version 6.

• querysetclasses [$classes ...]|[default] Sets the class names for highlighting individual sets (terms) in a query. Setting default restores the default, which is "queryset1". If the number of classes set is less than querysetcyclenum, the last class name is re-used, but the first integer substring within it is incremented; e.g. "queryset1" becomes "queryset2": thus consecutively-numbered class names do not all have to be listed. If an empty string is set, no per-set class highlighting is done. Classes are used with the C highlighting subflag of <fmt>. Added in version 6.

• queryclassesprefix $prefix|default

  Sets all highlighting classes (entire-query plus set classes) to the concatentation of $prefix and each class's default name. Provides a single way to ensure all class names are distinct. If "default" is set, uses the default prefix, which is none (i.e. resets all class names to defaults). Added in version 7.03.

• querysetcyclenum $n|default Sets maximum number of distinct sets (terms) in the query to highlight before recycling styles or classes. The default (which can be restored by setting default) is 10, which means that a query with more than 10 terms will re-use highlighting colors: terms 11-20 will be highlighted the same as terms 1-10, etc. Setting 0 is infinite, i.e. styles will not be recycled. If the cycle num exceeds the number of defined querysetstyles, the last style is re-used. If the cycle num exceeds the number of defined querysetclasses, the last class is re-used, but the first integer substring within it is incremented (e.g. "queryset1" becomes "queryset2"): this provides an easy way to automatically number classes. Added in version 6.

• highlightwithindoc on|off Whether to use the overall-query highlighting style/class querystyle/queryclass when the query has no delimiters or the delimiters are the whole document. Default is off, since highlighting the entire document is usually not helpful. Added in version 6.

• queryfixupmode withindot|findsets How to modify queries during highlighting so that all requested terms are highlighted (even if not all are needed to resolve query). The default is findsets, which will preserve the query and find all occurences of all non-NOT sets, within delimiters. In version 5 and earlier, the default was withindot, which appended "w/. @0" to the query and turned AND sets (+) into SET sets (=). findsets mode is more accurate, as it preserves the original delimiters and set logic; however withindot is more likely to find all sets regardless of query logic. Added in version 6.

DIAGNOSTICS
fmtcp has no effect on $ret.

CAVEATS
The fmtcp function was added in version 2.1.896760000 19980602. Some options were added in later versions as noted above.

It is not currently possible to Metamorph-markup and search-and-replace at the same time, e.g. have <mm> and <sb> active simultaneously.

SEE ALSO
fmt strfmt, mm, sb, rex split