MiniRobotLanguage (MRL)
STR.Parse
Extract Field from Delimited String
Intention
The STR.Parse command extracts the nth field from a source string (P1) based on a specified delimiter (P3) and field index (P2). The result is stored in a variable (P4) or pushed to the Top of Stack (TOS) if P4 is omitted.
The delimiter (P3) can be a single or multi-character string, treated as a single delimiter (e.g., ,. is one delimiter, not separate . and ,). If omitted, the default delimiter is a comma (,). The index (P2) is 1-based, where 1 is the first field. The search is case-sensitive.
This command is useful for parsing delimited data, such as CSV files or configuration strings. If the nth field is not found, an empty string is returned. For multiple single-character delimiters, use STR.GrabDelimited instead.
Schematic (Delimited Field Extraction)
Source: Hello,.this,.new,.world
Delimiter: ,. Index=1 --> Result: Hello
|H|e|l|l|o|,|.|t|h|i|s|,|.|n|e|w|,|.|w|o|r|l|d|
^ ^ (1st field before ,.)
Delimiter: ,. Index=3 --> Result: new
|H|e|l|l|o|,|.|t|h|i|s|,|.|n|e|w|,|.|w|o|r|l|d|
^ ^ (3rd field before ,.)
Syntax
STR.Parse|P1|P2[|P3][|P4]
Parameter Explanation
•P1 - (Source String) The string containing delimited fields. Variable or literal.
•P2 - (Field Index) Numeric, 1-based index of the field to extract (e.g., 1 for first field).
•P3 - (Optional Delimiter) Single or multi-character delimiter string (default is comma, ,). Treated as a single delimiter.
•P4 - (Optional Result Variable) Variable to store the extracted field. If omitted, result is pushed to TOS.
Examples
' Extract fields with multi-character delimiter to variable
STS.CLEAR
$$SRC=Hello,.this,.new,.world
$$DEL=,.
STR.Parse|$$SRC|1|$$DEL|$$RES
STS.CLEAR
' $$RES = Hello
STS.CLEAR
STR.Parse|$$SRC|3|$$DEL|$$RES
STS.CLEAR
' $$RES = new
' Extract field with default delimiter to TOS
STS.CLEAR
$$SRC=Hello,this,new,world
STR.Parse|$$SRC|2
POP.$$RES
STS.CLEAR
' $$RES = this
' Extract non-existent field to variable
STS.CLEAR
$$SRC=Hello,this
STR.Parse|$$SRC|3|$$RES
STS.CLEAR
' $$RES = "" (empty, no 3rd field)
'---------------------------------------------
' =================================================================
' SELF-VALIDATING TEST SCRIPT for STR.Parse
' Purpose: Verify all features with JIV. for automated checks and a summary report.
' Tests single/multi-character delimiters, 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. FIELD EXTRACTION TESTS
PRT. ===================================================
PRT. Test 1.1: Extract 1st field with multi-character delimiter to variable
STS.CLEAR
$$SRC=Hello,.this,.new,.world
$$DEL=,.
STR.Parse|$$SRC|1|$$DEL|$$RES
STS.CLEAR
$$EXP=Hello
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 3rd field with multi-character delimiter to variable
STS.CLEAR
$$SRC=Hello,.this,.new,.world
$$DEL=,.
STR.Parse|$$SRC|3|$$DEL|$$RES
STS.CLEAR
$$EXP=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 2nd field with default delimiter to TOS
STS.CLEAR
$$SRC=Hello,this,new,world
STR.Parse|$$SRC|2
$$TOS=#tos#
JIV.$$TOS!1|Lab_Error3
POV.$$RES
$$EXP=this
JIV.$$RES!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
Lab_Error3:
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP), Stack: $$TOS (exp: 1)
PRT.$$MSG
VIC.$$FAI
Lab_Next3:
STS.CLEAR
PRT. ===================================================
PRT. 2. EDGE CASE TESTS
PRT. ===================================================
PRT. Test 2.1: Empty source string (index=1, to variable)
STS.CLEAR
$$SRC=
$$DEL=,
STR.Parse|$$SRC|1|$$DEL|$$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 delimiters (index=1, to variable)
STS.CLEAR
$$SRC=HelloWorld
$$DEL=,
STR.Parse|$$SRC|1|$$DEL|$$RES
STS.CLEAR
$$EXP=HelloWorld
JIV.$$RES!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
Lab_Error5:
$$MSG= -> FAIL - Result: $$RES (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
Lab_Next5:
PRT. Test 2.3: Invalid index (index=5, to variable)
STS.CLEAR
$$SRC=Hello,this,new
$$DEL=,
STR.Parse|$$SRC|5|$$DEL|$$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: Zero index (index=0, to variable)
STS.CLEAR
$$SRC=Hello,this,new
$$DEL=,
STR.Parse|$$SRC|0|$$DEL|$$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 2.5: Binary data with delimiter (index=1, to variable)
STS.CLEAR
$$SRC=$crlf$Hello$sp$this$sp$new$tab$
$$DEL=$sp$
STR.Parse|$$SRC|1|$$DEL|$$RES
STS.CLEAR
$$EXP=$crlf$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: Empty delimiter (index=1, to variable)
STS.CLEAR
$$SRC=Hello,this,new
$$DEL=
STR.Parse|$$SRC|1|$$DEL|$$RES
STS.CLEAR
$$EXP=Hello,this,new
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 2.7: Trailing delimiter (index=4, to variable)
STS.CLEAR
$$SRC=Hello,this,new,
$$DEL=,
STR.Parse|$$SRC|4|$$DEL|$$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 delimiters.
-P2 must be positive and non-zero; negative or zero values return an empty string.
-P3 defaults to comma (,) if omitted.
-Result excludes the delimiter.
-If the nth field is not found, returns an empty string.
-Binary-safe for P1 and P3; no special/system vars expanded.
-For multiple single-character delimiters, use STR.GrabDelimited.
-Note: Implementation may leave unintended items on the stack; use STS.CLEAR after execution.
Limitations
-Treats P3 as a single delimiter, even if multi-character; for multiple single-character delimiters, use STR.GrabDelimited.
-Does not support nested delimiters or quoted fields; use STR.GetNested or STR.GrabQuoted for those cases.
-Current implementation may corrupt stack; clear stack after use.
See also: