MiniRobotLanguage (MRL)
BLO.GrabQuoted
Extract Quoted Substring by Index
Intention
This command extracts the n'th quoted substring from a source string (P1) based on the index (P2), using a specified single quote character (P3).
The result is stored in a variable (P4) or pushed to the Top of Stack (TOS) if P4 is omitted.
The search is case-sensitive and extracts the substring between the nth pair of quote characters (e.g., double quotes "..." or single quotes '...'), excluding the quotes.
If P3 is omitted, the default quote character is the double quote (ASCII 34, "). The index (P2) is 1-based, where 1 is the first quoted substring.
This command is useful for parsing quoted terms in structured data, such as command-line arguments, CSV fields, or code literals.
If the nth quoted substring is not found, an empty string is returned.
Schematic (Quoted Substring Extraction)
Source: "Hello" 'World' "MiniRobot"!
Quote: ', Index=1 --> Result: World
|"|H|e|l|l|o|"| |'|W|o|r|l|d|'| |"|M|i|n|i|R|o|b|o|t|"|!|
^ ^ (1st '...' pair)
Quote: ", Index=2 --> Result: MiniRobot
|"|H|e|l|l|o|"| |'|W|o|r|l|d|'| |"|M|i|n|i|R|o|b|o|t|"|!|
^ ^ (2nd "..." pair)
Syntax
BLO.GrabQuoted|P1|P2[|P3][|P4]
Parameter Explanation
•P1 - (Source String) The string containing quoted terms. Variable or literal.
•P2 - (Index) Numeric, 1-based index of the quoted term to extract (e.g., 1 for first term).
•P3 - (Optional Quote Character) The quote character (e.g., " or '). Default is double quote (ASCII 34, ").
•P4 - (Optional Result Variable) Variable to store the extracted substring. If omitted, result is pushed to TOS.
Examples
' Extract second single-quoted term to variable
STS.CLEAR
$$SRC="Hello" 'World' 'MiniRobot'!
$$IDX=2
$$QUO='
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
' $$RES = MiniRobot
' Extract first double-quoted term to TOS
STS.CLEAR
$$SRC="Hello" 'World' "MiniRobot"!
$$IDX=1
BLO.GrabQuoted|$$SRC|$$IDX
POP.$$RES
STS.CLEAR
' $$RES = Hello
' Extract non-existent quoted term to variable
STS.CLEAR
$$SRC="Hello" 'World'
$$IDX=3
$$QUO='
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
' $$RES = "" (empty, no 3rd single-quoted term)
'---------------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for BLO.GrabQuoted
' Purpose: Verify all features with JIV. for automated checks and a summary report.
' Tests different quote characters, index values, result to variable/TOS, edge cases.
' Uses result variable $$RES for most tests, with stack access for TOS tests.
' Includes extra stack clearing to avoid corruption.
' Uses short jumps (JIV.) and clear PRT. for readability.
' =================================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. QUOTED TERM EXTRACTION TESTS
PRT. ===================================================
PRT. Test 1.1: Extract 2nd single-quoted term to variable
STS.CLEAR
$$SRC="Hello" 'World' 'MiniRobot'!
$$IDX=2
$$QUO='
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
$$EXP=MiniRobot
JIV.$$RES!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next1
PRT. Test 1.2: Extract 1st double-quoted term to TOS
STS.CLEAR
$$SRC="Hello" 'World' "MiniRobot"!
$$IDX=1
BLO.GrabQuoted|$$SRC|$$IDX
$$TOS=#tos#
JIV.$$TOS!1|Lab_Error2
POV.$$RES
$$EXP=Hello
JIV.$$RES!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP), Stack: $$TOS (exp: 1)
PRT.$$MSG
VIC.$$FAI
:Lab_Next2
STS.CLEAR
PRT. Test 1.3: Extract 2nd double-quoted term to variable
STS.CLEAR
$$SRC="Hello" 'World' "MiniRobot"!
$$IDX=2
$$QUO="
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
$$EXP=MiniRobot
JIV.$$RES!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next3
PRT. ===================================================
PRT. 2. EDGE CASE TESTS
PRT. ===================================================
PRT. Test 2.1: Empty source string (index=1, to variable)
STS.CLEAR
$$SRC=
$$IDX=1
$$QUO="
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
$$EXP=
JIV.$$RES!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next4
PRT. Test 2.2: No quoted terms (index=1, to variable)
STS.CLEAR
$$SRC=Hello World
$$IDX=1
$$QUO="
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
$$EXP=
JIV.$$RES!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next5
PRT. Test 2.3: Invalid index (index=3, to variable)
STS.CLEAR
$$SRC="Hello" 'World'
$$IDX=3
$$QUO='
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
$$EXP=
JIV.$$RES!$$EXP|Lab_Error6
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next6
:Lab_Error6
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next6
PRT. Test 2.4: Non-standard quote character (index=1, to variable)
STS.CLEAR
$$SRC=#Hello#World#
$$IDX=1
$$QUO=#
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
$$EXP=Hello
JIV.$$RES!$$EXP|Lab_Error7
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next7
:Lab_Error7
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next7
PRT. Test 2.5: Binary data with quotes (index=1, to variable)
STS.CLEAR
$$SRC=$crlf$"Hello"$sp$"World"$tab$
$$IDX=1
$$QUO="
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
$$EXP=Hello
JIV.$$RES!$$EXP|Lab_Error8
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next8
:Lab_Error8
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next8
PRT. Test 2.6: Invalid quote character (index=1, to variable)
STS.CLEAR
$$SRC="Hello" 'World'
$$IDX=1
$$QUO=@
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
$$EXP=
JIV.$$RES!$$EXP|Lab_Error9
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next9
:Lab_Error9
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next9
PRT. Test 2.7: Zero index (index=0, to variable)
STS.CLEAR
$$SRC="Hello" 'World'
$$IDX=0
$$QUO="
BLO.GrabQuoted|$$SRC|$$IDX|$$QUO|$$RES
STS.CLEAR
$$EXP=
JIV.$$RES!$$EXP|Lab_Error10
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next10
:Lab_Error10
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next10
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.
Remarks
-Case-sensitive search for quote characters.
-P2 must be positive and non-zero; negative or zero values return an empty string.
-P3 defaults to double quote (ASCII 34, ") if omitted.
-Result excludes the quote characters.
-If the nth quoted term is not found, returns an empty string.
-Binary-safe for P1 and P3; no special/system vars expanded.
-For extracting nested substrings, use BLO.GetNested.
-Note: Implementation may leave unintended items on the stack; use STS.CLEAR after execution.
Limitations
-Does not support nested quotes or escaped quotes within quoted terms.
-Only extracts terms enclosed by identical quote characters (P3).
-No wildcard or pattern support; use STR.FindAny for patterns.
-Current implementation may corrupt stack; clear stack after use.
See also: