MiniRobotLanguage (MRL)
STR.FindAny
General Multi-Instring Command: Search for the First Matching Term from Multiple Terms
Intention
This command searches for the first occurrence of any term from a comma-delimited list of search strings (P2) within a source string (P1), starting from an optional position (P3), using a specified mode (P4). It pushes two values to the stack (top to bottom):
1. Term index (1-based) of the found term (or 0 if not found).
2. The found term (or "-" if not found).
The search is left-to-right, stopping at the first match. Modes include InString matches, exact matches, case-insensitive searches, wildcards, or standard patterns. This is ideal for tasks like keyword detection, log parsing, or multi-term validation without loops.
P2 terms are comma-delimited (e.g., Term1,Term2). Terms cannot contain commas unless quoted (e.g., "Term,1"). The source (P1) is not modified.
Schematic (Multi-Term Search)
Source: ABCDEFG$crlf$123456$crlf$abcdefg$crlf$
Search Terms: BC,FG (mode i)
Search --> |A|B|C|D|E|F|G|...|
^ (Matches BC, term 1)
Stack (top to bottom): 1, BC
Syntax
STR.FindAny|P1|P2[|P3][|P4]
Parameter Explanation
•P1 - (Source String) The main string to search within. Variable or literal.
•P2 - (Search Strings) Comma-delimited terms (e.g., Term1,Term2). Quote terms with commas (e.g., "Term,1"). Found term pushed to stack (or "-").
•P3 - (Optional Start Position) Numeric, 1-based (default 1). No reverse search.
•P4 - (Optional Mode) i (default: InString, trimmed), e (exact), ec (exact case-insensitive), ic (InString case-insensitive), w (wildcards ?*), wc (wildcards case-insensitive), s (standard patterns).
Mode Explanation
•i - (Default) InString: Term is contained in source (case-sensitive, trimmed).
•e - Exact: Source must exactly match term (case-sensitive).
•ec - Exact Case-Insensitive: Source must exactly match term (case-insensitive).
•ic - InString Case-Insensitive: Term is contained in source (case-insensitive).
•w - Wildcards: Terms use ? (single char) and * (any chars, case-sensitive).
•wc - Wildcards Case-Insensitive: Terms use ? and * (case-insensitive).
•s - Standard Patterns: Terms use patterns like {&DOCAPS:}, {&OR:}, etc.
Wildcard Explanation
In modes w and wc, wildcards enable flexible matching:
•? - Matches any single character. E.g., H?llo matches Hello, Hallo.
•* - Matches any sequence of characters (including none). E.g., H*World matches HWorld, HelloWorld.
Mode wc combines wildcards with case-insensitive matching (e.g., h*world matches HelloWorld).
Example: $$TXT=Hello123World, $$SEA=Hel?o*World,H*123*, mode w returns stack: 1, Hel?o*World.
Standard Pattern Explanation
In mode s, standard patterns allow complex logical matching:
•{&DOCAPS:} ({&00:}) - Case-sensitive match. E.g., {&DOCAPS:Theo} matches Theo, not theo.
•{&OR:} ({&01:}) - Matches either term. E.g., {Text1&OR:Text2} matches Text1 or Text2.
•{&XOR:} ({&02:}) - Matches exactly one term. E.g., {Text1&XOR:Text2} matches Text1 or Text2, not both.
•{&AND:} ({&03:}) - Matches if both terms present. E.g., {Text1&AND:Text2} requires Text1 and Text2.
•{&ANDTHEN:} ({&04:}) - Matches terms in order. E.g., {Text1&ANDTHEN:Text2} requires Text1 before Text2.
•{&FUZZY:} ({&05:}) - Fuzzy match with [value] errors. E.g., {{Text1}&FUZZY:2} allows 2 char differences.
•{&TOLERANT:} ({&06:}) - Tolerant match with [value] errors. E.g., {{Text1}&TOLERANT:1} allows 1 error.
•{&NOT:} ({&07:}) - Matches if term absent. E.g., {&NOT:Text1} succeeds if Text1 not found.
•{&EXACT:} ({&08:}) - Exact whole-string match. E.g., {&EXACT:Text1} requires full string Text1.
•{&NOTEXT:} ({&09:}) - Matches empty string. E.g., {&NOTEXT:} succeeds on empty string.
•{&WILDC:} ({&0c:}) - Wildcard pattern. E.g., {&WILDC:Hallo??.*} matches Hallo12World.
Patterns can be nested (e.g., "{&DOCAPS:{Text1&OR:Text2}}"). Mode s requires terms to use these patterns; other modes use plain text or wildcards.
Example: $$TXT=TheoGottwald Internet, $$SEA={&DOCAPS:TheoGottwald&ANDTHEN:Internet}, mode s returns stack: 1, {&DOCAPS:TheoGottwald&ANDTHEN:Internet}.
Examples
' InString match (default mode i)
$$TXT=ABCDEFG$crlf$123456$crlf$abcdefg$crlf$
$$SEA=BC,FG
STR.FindAny|$$TXT|$$SEA|1|i
' Stack (top to bottom): 1, BC
' Exact match (mode e)
$$TXT=Hello World
$$SEA=Hello World,Other
STR.FindAny|$$TXT|$$SEA|1|e
' Stack: 1, Hello World
' Case-insensitive InString (mode ic)
$$TXT=HELLO world
$$SEA=hello,world
STR.FindAny|$$TXT|$$SEA|1|ic
' Stack: 1, hello
' Wildcards (mode w)
$$TXT=Hello123World
$$SEA=Hel?o*World,H*123*
STR.FindAny|$$TXT|$$SEA|1|w
' Stack: 1, Hel?o*World
' Standard pattern (mode s)
$$TXT=TheoGottwald Internet
$$SEA={&DOCAPS:TheoGottwald&ANDTHEN:Internet},{&EXACT:Explorer}
STR.FindAny|$$TXT|$$SEA|1|s
' Stack: 1, {&DOCAPS:TheoGottwald&ANDTHEN:Internet}
ENR.
'---------------------------------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for STR.FindAny (Multi-Term First Match Search)
' Purpose: Verify all features with JIV. for automated checks and a summary report.
' Tests modes (i,e,ec,ic,w,wc,s), wildcards (?/*), patterns ({&DOCAPS:}, {&OR:}, etc.),
' returns term index and found term on stack, edge cases (empty, invalid start/mode).
' Stack: TOS (Stackpos: 0)=term index (1-based or 0), Stackpos: 1=found term (or "-").
' Uses short jumps (JIV.) and clear PRT. for readability.
' P2 terms are comma-delimited without quotes unless containing commas.
' Corrected: Stack retrieval order (TOS=term index, next=found term).
' =================================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. INSTRING MATCH TEST (MODE i)
PRT. ===================================================
PRT. Test 1.1: InString match for BC (term 1) in ABCDEFG... (mode i, pos=1)
$$TXT=ABCDEFG$crlf$123456$crlf$abcdefg$crlf$
$$SEA=BC,FG
STR.FindAny|$$TXT|$$SEA|1|i
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error1
POV.$$TIX|$$FND
$$EXP=1
JIV.$$TIX!$$EXP|Lab_Error1
$$EXP=BC
JIV.$$FND!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next1
STS.CLEAR
PRT. Test 1.2: InString match for FG (term 2) after XBC fails (mode i, pos=1)
$$SEA=XBC,FG
STR.FindAny|$$TXT|$$SEA|1|i
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error2
POV.$$TIX|$$FND
$$EXP=2
JIV.$$TIX!$$EXP|Lab_Error2
$$EXP=FG
JIV.$$FND!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next2
STS.CLEAR
PRT. ===================================================
PRT. 2. EXACT MATCH TEST (MODE e)
PRT. ===================================================
PRT. Test 2.1: Exact match for Hello World (term 1) in Hello World (mode e, pos=1)
$$TXT=Hello World
$$SEA=Hello World,Other
STR.FindAny|$$TXT|$$SEA|1|e
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error3
POV.$$TIX|$$FND
$$EXP=1
JIV.$$TIX!$$EXP|Lab_Error3
$$EXP=Hello World
JIV.$$FND!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next3
STS.CLEAR
PRT. ===================================================
PRT. 3. CASE-INSENSITIVE EXACT TEST (MODE ec)
PRT. ===================================================
PRT. Test 3.1: Case-insensitive exact hello world (term 1) in Hello World (mode ec, pos=1)
$$TXT=Hello World
$$SEA=hello world,Other
STR.FindAny|$$TXT|$$SEA|1|ec
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error4
POV.$$TIX|$$FND
$$EXP=1
JIV.$$TIX!$$EXP|Lab_Error4
$$EXP=hello world
JIV.$$FND!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next4
STS.CLEAR
PRT. ===================================================
PRT. 4. CASE-INSENSITIVE INSTRING TEST (MODE ic)
PRT. ===================================================
PRT. Test 4.1: Case-insensitive InString hello (term 1) in HELLO world (mode ic, pos=1)
$$TXT=HELLO world
$$SEA=hello,world
STR.FindAny|$$TXT|$$SEA|1|ic
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error5
POV.$$TIX|$$FND
$$EXP=1
JIV.$$TIX!$$EXP|Lab_Error5
$$EXP=hello
JIV.$$FND!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next5
STS.CLEAR
PRT. ===================================================
PRT. 5. WILDCARDS TEST (MODE w)
PRT. ===================================================
PRT. Test 5.1: Wildcard Hel?o*World (term 1) in Hello123World (mode w, pos=1)
$$TXT=Hello123World
$$SEA=Hel?o*World,H*123*
STR.FindAny|$$TXT|$$SEA|1|w
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error6
POV.$$TIX|$$FND
$$EXP=1
JIV.$$TIX!$$EXP|Lab_Error6
$$EXP=Hel?o*World
JIV.$$FND!$$EXP|Lab_Error6
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next6
:Lab_Error6
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next6
STS.CLEAR
PRT. ===================================================
PRT. 6. CASE-INSENSITIVE WILDCARDS TEST (MODE wc)
PRT. ===================================================
PRT. Test 6.1: Case-insensitive wildcard Hello*World (term 1) in hello123world (mode wc, pos=1)
$$TXT=hello123world
$$SEA=Hello*World,hel?123*
STR.FindAny|$$TXT|$$SEA|1|wc
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error7
POV.$$TIX|$$FND
$$EXP=1
JIV.$$TIX!$$EXP|Lab_Error7
$$EXP=Hello*World
JIV.$$FND!$$EXP|Lab_Error7
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next7
:Lab_Error7
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next7
STS.CLEAR
PRT. ===================================================
PRT. 7. STANDARD PATTERN TEST (MODE s)
PRT. ===================================================
PRT. Test 7.1: Pattern {&DOCAPS:TheoGottwald&ANDTHEN:Internet} (term 1) in TheoGottwald Internet Explorer (mode s, pos=1)
$$TXT=TheoGottwald Internet Explorer
$$SEA={&DOCAPS:TheoGottwald&ANDTHEN:Internet},{&EXACT:Explorer}
STR.FindAny|$$TXT|$$SEA|1|s
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error8
POV.$$TIX|$$FND
$$EXP=1
JIV.$$TIX!$$EXP|Lab_Error8
$$EXP={&DOCAPS:TheoGottwald&ANDTHEN:Internet}
JIV.$$FND!$$EXP|Lab_Error8
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next8
:Lab_Error8
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next8
STS.CLEAR
PRT. Test 7.2: Pattern FUZZY match {TheoGottwald}&FUZZY:1 (term 1) in TheaGottwald Internet (mode s, pos=1)
$$TXT=TheaGottwald Internet
$$SEA={TheoGottwald&FUZZY:1},{&EXACT:Explorer}
STR.FindAny|$$TXT|$$SEA|1|s
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error9
POV.$$TIX|$$FND
$$EXP=1
JIV.$$TIX!$$EXP|Lab_Error9
$$EXP={TheoGottwald&FUZZY:1}
JIV.$$FND!$$EXP|Lab_Error9
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next9
:Lab_Error9
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next9
STS.CLEAR
PRT. ===================================================
PRT. 8. NO MATCH TEST
PRT. ===================================================
PRT. Test 8.1: No match for Zebra,Elephant in Hello World (mode i, pos=1)
$$TXT=Hello World
$$SEA=Zebra,Elephant
STR.FindAny|$$TXT|$$SEA|1|i
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error10
POV.$$TIX|$$FND
$$EXP=0
JIV.$$TIX!$$EXP|Lab_Error10
$$EXP=-
JIV.$$FND!$$EXP|Lab_Error10
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next10
:Lab_Error10
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next10
STS.CLEAR
PRT. ===================================================
PRT. 9. EDGE CASE TESTS
PRT. ===================================================
PRT. Test 9.1: Empty source string (mode i, pos=1)
$$TXT=
$$SEA=A,B
STR.FindAny|$$TXT|$$SEA|1|i
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error11
POV.$$TIX|$$FND
$$EXP=0
JIV.$$TIX!$$EXP|Lab_Error11
$$EXP=-
JIV.$$FND!$$EXP|Lab_Error11
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next11
:Lab_Error11
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next11
STS.CLEAR
PRT. Test 9.2: Empty search terms (mode i, pos=1)
$$TXT=Hello
$$SEA=
STR.FindAny|$$TXT|$$SEA|1|i
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error12
POV.$$TIX|$$FND
$$EXP=0
JIV.$$TIX!$$EXP|Lab_Error12
$$EXP=-
JIV.$$FND!$$EXP|Lab_Error12
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next12
:Lab_Error12
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next12
STS.CLEAR
PRT. Test 9.3: Start position beyond source length (mode i, pos=10)
$$TXT=AB
$$SEA=A
STR.FindAny|$$TXT|$$SEA|10|i
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error13
POV.$$TIX|$$FND
$$EXP=0
JIV.$$TIX!$$EXP|Lab_Error13
$$EXP=-
JIV.$$FND!$$EXP|Lab_Error13
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next13
:Lab_Error13
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next13
STS.CLEAR
PRT. Test 9.4: Invalid mode defaults to i (search hello in Hello, pos=1)
$$TXT=Hello
$$SEA=hello
STR.FindAny|$$TXT|$$SEA|1|z
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error14
POV.$$TIX|$$FND
$$EXP=0
JIV.$$TIX!$$EXP|Lab_Error14
$$EXP=-
JIV.$$FND!$$EXP|Lab_Error14
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next14
:Lab_Error14
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next14
STS.CLEAR
PRT. Test 9.5: Term with commas (mode i, pos=1)
$$TXT=Hello, World, Goodbye
$$SEA=Goodbye
STR.FindAny|$$TXT|$$SEA|1|i
$$TOS=#tos#
JIV.$$TOS!2|Lab_Error15
POV.$$TIX|$$FND
$$EXP=1
JIV.$$TIX!$$EXP|Lab_Error15
$$EXP=Goodbye
JIV.$$FND!$$EXP|Lab_Error15
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next15
:Lab_Error15
$$MSG= -> FAIL - Term Index: $$TIX (exp: $$EXP), Found: $$FND (exp: $$EXP), Stack: $$TOS (exp: 2)
PRT.$$MSG
VIC.$$FAI
:Lab_Next15
STS.CLEAR
PRT. ===================================================
PRT. TEST SUMMARY
PRT. ===================================================
CAL.$$TOT=$$PAS+$$FAI
$$MSG=Total Tests: $$TOT
PRT.$$MSG
$$MSG=Passed: $$PAS
PRT.$$MSG
$$MSG=Failed: $$FAI
PRT.$$MSG
' Display final result
JIV.$$FAI=0|Lab_Success
$$MSG=FAILURE: $$FAI of $$TOT tests failed.
MBX.$$MSG|Test Result|16
JMP.Lab_End
:Lab_Success
MBX.SUCCESS: All tests passed!|Test Result|64
:Lab_End
ENR.
The Command passed all tests.
Remarks
-Default case-sensitive (modes i, e, w, s); use ec/ic/wc for case-insensitive.
-P2 terms cannot contain commas unless quoted; found term pushed to stack.
-TOS is term index (1-based); 0 and "-" if no match.
-Mode i trims terms; others preserve exact input.
-P3 defaults to 1; no reverse search (unlike STR.FIND).
-Binary-safe for P1; P2 parsed as comma-delimited text.
Limitations
-P2 terms cannot contain commas unless quoted; complex parsing may require preprocessing.
-Returns term index, not string position; use STR.FIND for position-based search.
-Wildcards (?/*) only in w/wc; patterns only in s.
-No reverse search; use STR.FIND for RTL.
See also: