The LazyBoy Library Manual - StrFuncParser

Part of the Strings group.

%imacro StrFuncParser 3
Prefers: label, ES:DI, label

Indexed string table callback function dispatch parser. Wow, that is a mouthful and is far easier to use than it sounds. Basically, you create a simple table within the code segment consisting of labels and strings using the StrFuncTable macro. Then use this macro in combination with that table to parse a string.

%1 is the label in the code segment label for string function dispatch table.

%2 is the register pair pointer to the string that will be parsed. If no segment is provided, ES is assumed. Unless %2 is a LABEL, then CS is assumed.

%3 is a list of characters that will be used to separate the string into sub-strings. It can be provided as a hard coded text string, a LABEL or a register pair pointer. If it is a pointer and no segment is provided, DS will be assumed. If it is a LABEL, then CS is assumed.

A caseless search is performed on the entries in the table for each sub-string. If a match is found, the relavent callback function will be called. The last entry in the table is a NULL string and acts as a catch-all, it will be called when no match is found.

All quote character's (", ' or `) regardless of their position in the sub-string will begin a quoted text. No separators or other quote characters will be processed until the same quote character is used to end the quoted text portion of the sub-string. The quote character does not need to be the first character in the sub-string for a quoted text section.

When the parser calls the relative callback function, it will provide the following information:

  • Carry Flag will be set, if no match was found for the sub-string.
  • ES:DI will point to the ASCIIZ sub-string. For matched items this will be the text that matched the table entry. For the catch-all function, it may be a switch, text or a NULL ASCIIZ string. The string will include the leading separator character unless that separator was a space character.
  • ES:BX will point to the ASCIIZ sub-string terminator.
  • AX will be the address of the previous callback function or 0x0000 when it is the very first call made by the dispatcher.
  • DL is the leading separator character for the sub-string that matched a character in %3 or NULL.
  • DH When the dispatcher calls the callback function, it temporarily replaces the trailing separator with a NULL. DH is the original trailing separator character.
  • DS:SI Will have the same value as when StrFuncParser was invoked.

Except for the stack, the callback function does not need to preserve any of the registers.

On return from the callback function, if the Carry Flag is set, parsing will be aborted and StrFuncParser will return with CF set to indicate processing was not completed.

Examples:

    StrFuncParser OPTS, es:di, "/\,. "   ; Parse string at es:di

See also: StrFuncTable.