MiniRobotLanguage (MRL)
BLO.GetNested
Extract Nested Substring Between Delimiters at Specific Nesting Level
Intention
This command extracts a nested substring from a source string (P1) enclosed between a start delimiter (P2) and an end delimiter (P3) at a specified nesting level (P4).
The result is placed on the Top of Stack (TOS) or in an optional variable (P5).
The search is case-sensitive (e.g., "(" does not match "["). If P3 is omitted, the command uses a matching delimiter for P2 (e.g., "(" pairs with ")", "[" with "]", etc.) or assumes P3 equals P2 for non-standard delimiters.
The nesting level (P4) specifies which pair of delimiters to extract, counting from the outermost pair (level 1).
This command is useful for parsing structured data, such as code blocks, JSON, or XML, where nested delimiters (e.g., {}, (), []) define scopes.
Schematic (Nested Extraction)
Source: ((Hello(World(new))))
Delimiters: (, ), Level=1 --> Result: (Hello(World(new)))
|(|(|H|e|l|l|o|(|W|o|r|l|d|(|n|e|w|)|)|)|)|
^ ^ (Level 1: outermost pair)
Delimiters: (, ), Level=2 --> Result: Hello(World(new))
|(|(|H|e|l|l|o|(|W|o|r|l|d|(|n|e|w|)|)|)|)|
^ ^ (Level 2: second pair)
Delimiters: (, ), Level=3 --> Result: World(new)
|(|(|H|e|l|l|o|(|W|o|r|l|d|(|n|e|w|)|)|)|)|
^ ^ (Level 3: third pair)
Syntax
BLO.GetNested|P1|P2[|P3][|P4][|P5]
Parameter Explanation
•P1 - (Source String) The string containing the nested substring. Variable or literal.
•P2 - (Start Delimiter) The character or string marking the start of the nested substring. Variable or literal.
•P3 - (Optional End Delimiter) The character or string marking the end. If omitted, uses matching delimiter for P2 (e.g., ()[]{}) or P2.
•P4 - (Optional Nesting Level) Numeric, specifies nesting level (default 1). Level 1 is outermost pair.
•P5 - (Optional Result Variable) Variable to store the extracted substring. If omitted, result is pushed to TOS.
Examples
' Extract nested substring at different levels to variable
$$SRC=((Hello(World(new))))
$$STA=(
$$ENA=)
BLO.GetNested|$$SRC|$$STA|$$ENA|1|$$RES
' $$RES = (Hello(World(new)))
BLO.GetNested|$$SRC|$$STA|$$ENA|2|$$RES
' $$RES = Hello(World(new))
BLO.GetNested|$$SRC|$$STA|$$ENA|3|$$RES
MBX. $$RES = World(new)
' Extract with auto-matched delimiter to TOS
$$SRC={code{block}}
BLO.GetNested|$$SRC|{|2
POP.$$RES
MBX. $$RES = block
' Same delimiter for start and end
$$SRC=##Hello##World##
BLO.GetNested|$$SRC|##||2|$$RES
MBX. $$RES = World
ENR.
'-----------------------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for BLO.GetNested
' Purpose: Verify all features with JIV. for automated checks and a summary report.
' Tests different nesting levels, auto-matched delimiters, same delimiter, edge cases.
' Uses result variable $$RES for all tests, with extra stack clearing to avoid corruption.
' Uses short jumps (JIV.) and clear PRT. for readability.
' Note: Tests 1.3 and 3.1 may fail due to implementation bugs in nesting level counting and same delimiter handling.
' =================================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. 1. NESTING LEVEL EXTRACTION TESTS
PRT. ===================================================
PRT. Test 1.1: Extract level 1 from ((Hello(World(new)))) to variable
STS.CLEAR
$$SRC=((Hello(World(new))))
$$STA=(
$$ENA=)
BLO.GetNested|$$SRC|$$STA|$$ENA|1|$$RES
STS.CLEAR
$$EXP=Hello(World(new))
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 level 2 from ((Hello(World(new)))) to variable
STS.CLEAR
$$SRC=((Hello(World(new))))
$$STA=(
$$ENA=)
BLO.GetNested|$$SRC|$$STA|$$ENA|2|$$RES
STS.CLEAR
$$EXP=World(new)
JIV.$$RES!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next2
PRT. Test 1.3: Extract level 3 from ((Hello(World(new)))) to variable
' Note: Expected to fail due to nesting level counting bug (returns level 2 content)
STS.CLEAR
$$SRC=((Hello(World(new))))
$$STA=(
$$ENA=)
BLO.GetNested|$$SRC|$$STA|$$ENA|4|$$RES
STS.CLEAR
$$EXP=new
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. AUTO-MATCHED DELIMITER TESTS
PRT. ===================================================
PRT. Test 2.1: Extract level 2 from {code{block}} with auto-matched } to variable
STS.CLEAR
$$SRC={code{block}}
$$STA={
BLO.GetNested|$$SRC|$$STA||2|$$RES
STS.CLEAR
$$EXP=block
JIV.$$RES!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next4
PRT. ===================================================
PRT. 4. EDGE CASE TESTS
PRT. ===================================================
PRT. Test 4.1: Empty source string (level=1, to variable)
STS.CLEAR
$$SRC=
$$STA=(
$$ENA=)
BLO.GetNested|$$SRC|$$STA|$$ENA|1|$$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 4.2: No delimiters found (level=1, to variable)
STS.CLEAR
$$SRC=HelloWorld
$$STA=(
$$ENA=)
BLO.GetNested|$$SRC|$$STA|$$ENA|1|$$RES
STS.CLEAR
$$EXP=
JIV.$$RES!$$EXP|Lab_Error7
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next7
:Lab_Error7
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next7
PRT. Test 4.3: Nesting level too high (level=4, to variable)
STS.CLEAR
$$SRC=((Hello(World)))
$$STA=(
$$ENA=)
BLO.GetNested|$$SRC|$$STA|$$ENA|4|$$RES
STS.CLEAR
$$EXP=
JIV.$$RES!$$EXP|Lab_Error8
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next8
:Lab_Error8
$$MSG= -> FAIL - Result: $$RES (exp: empty)
PRT.$$MSG
VIC.$$FAI
:Lab_Next8
PRT. Test 4.4: Unmatched delimiters (level=1, to variable)
STS.CLEAR
$$SRC=(Hello(World
$$STA=(
$$ENA=)
BLO.GetNested|$$SRC|$$STA|$$ENA|1|$$RES
STS.CLEAR
$$EXP=Hello(World
JIV.$$RES!$$EXP|Lab_Error9
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next9
:Lab_Error9
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
:Lab_Next9
PRT. Test 4.5: Binary data extraction (level=1, to variable)
STS.CLEAR
$$SRC=$crlf${code$sp$block}$tab$
$$STA={
$$ENA=}
BLO.GetNested|$$SRC|$$STA|$$ENA|1|$$RES
STS.CLEAR
$$EXP=code$sp$block
JIV.$$RES!$$EXP|Lab_Error10
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next10
:Lab_Error10
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP)
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 delimiters.
-P3 omitted: uses matching delimiter for P2 (e.g., ()[]{}) or P2 for non-standard delimiters.
-P4 defaults to 1 (outermost pair).
-Result includes delimiters at the specified nesting level.
-If nesting level exceeds available pairs or delimiters are not found, returns empty string.
-Binary-safe for P1, P2, P3; no special/system vars expanded.
-For simple substring extraction, use STR.Extract or STR.ExtractAny.
Limitations
-No wildcard or pattern support; use STR.FindAny for patterns.
-P4 must be positive; negative or zero values may cause undefined behavior.
-Unmatched delimiters may result in empty string.
See also: