MiniRobotLanguage (MRL)
BCH. Command
Before Character
Intention
Extracts the portion of a source string (P1) that occurs before a specified occurrence of a delimiter string (P2). An optional index (P3) determines which occurrence of the delimiter is used, counting from the left (positive index) or right (negative index). The delimiter itself is excluded from the result. The result is stored in an optional target variable (P4) or the special variable $tos$ if omitted.
Syntax
BCH.P1|P2[|P3][|P4]
Parameter Explanation
P1 - Variable containing the source string (e.g., $$SRC). The content of this variable will be processed.
P2 - The delimiter character or string to search for within P1.
Important: This parameter cannot be the pipe symbol (|) due to SPR script command parameter separation rules. If you need to use a pipe as the delimiter, use the special variable $pip$ instead.
P3 - (Optional) The occurrence index of the delimiter (P2) to use as the split point.
•Default if omitted: 1 (the first occurrence from the left).
•Positive number (e.g., 3): The 3rd occurrence from the left.
•Negative number (e.g., -2): The 2nd occurrence from the right.
•0 is an invalid index.
P4 - (Optional) The variable name (e.g., $$OUT) where the result (the part of the string before the delimiter) will be stored. Must be a valid 5-character variable name ($$xxx).
•If P4 is omitted (i.e., only P1|P2 or P1|P2|P3 are provided) or if P4 is provided as an empty string (P1|P2|P3|), the result is stored in the special variable $tos$ (Top of Stack). You can retrieve this value using POP.
Examples
' Example 1: Get filename without extension (part before last dot)
VAR.$$SRC=C:\Folder\MyFile.txt
' Use Index -1 to find the last dot
BCH.$$SRC|.|-1|$$NAM
' Output: C:\Folder\MyFile
DBP.$$NAM
' Example 2: Get URL part before 3rd slash, result to $tos$
VAR.$$URL=http://www.fa2.de/index.html
' P4 omitted, result goes to $tos$
BCH.$$URL|/|3
POP.$$OUT
' Output: http://www.fa2.de
DBP.$$OUT
' Example 3: Get part before 2nd pipe from right, using $pip$
VAR.$$DAT=A|B|C|D|E
BCH.$$DAT|$pip$|-2|$$RES
' Output: A|B|C|D
DBP.$$RES
VAR.$$DAT=A|B|C|D|E
BCH.$$DAT|$pip$||$$RES
' Output: A
DBP.$$RES
Output of Sample-Code.
Remarks
- The delimiter character/string itself (P2) is excluded from the returned result.
- If the specified delimiter (P2) or the specified occurrence (P3) is not found in the source string (P1), the command will not store any result. The target variable (P4 or $tos$) will retain its previous value.
Limitations
- The delimiter specified in P2 cannot be the pipe symbol (|) directly, as it conflicts with the SPR command parameter separator. Use the special variable $pip$ if you need to split by a pipe character.
Sample Script
'SPR Script-file: BCH_ACH_Test_CorrectVars (Included as Example)
'Purpose: Comprehensive test for BCH. and ACH. commands with valid vars
'Author: MINIPC\theog
'Creation date: 03-26-2025
'Updated: 04-08-2024 (Corrected variable names, pipe tests logic)
'===========================================================
'#EXE:?path\
'#SPI:ForceWrite
' Declare valid variables ( $$ + 3 characters = 5 total )
VAR.$$SRC=
VAR.$$OUT=
VAR.$$LOG=
' Use unique value for unchanged check
VAR.$$FIX=__NO_CHANGE_EXPECTED__
VAR.$$NUL=
' --- Test Suite Start ---
VAV.$$LOG=$crlf$=== Starting BCH/ACH Revised Test Suite (Valid Vars, using $pip$) ===$crlf$
PRT.$$LOG
' --- Basic Cases ---
' Test 1: Simple BCH with dot, Target $$OUT
VAV.$$SRC=C:\Folder\MyFile.txt
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 1: BCH ($$SRC='$$SRC') with '.', Index=1, Target=$$OUT (expecting 'C:\Folder\MyFile')$crlf$
PRT.$$LOG
BCH.$$SRC|.|1|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=C:\Folder\MyFile
VAV.$$LOG=Test 1 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 1 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 2: Simple ACH with dot, Target $$OUT
VAV.$$SRC=C:\Folder\MyFile.txt
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 2: ACH ($$SRC='$$SRC') with '.', Index=1, Target=$$OUT (expecting 'txt')$crlf$
PRT.$$LOG
ACH.$$SRC|.|1|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=txt
VAV.$$LOG=Test 2 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 2 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 3: BCH with backslash, Last occurrence (-1), Target $$OUT
VAV.$$SRC=C:\Folder\SubFolder\File.txt
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 3: BCH ($$SRC='$$SRC') with '\', Index=-1, Target=$$OUT (expecting 'C:\Folder\SubFolder')$crlf$
PRT.$$LOG
BCH.$$SRC|\|-1|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=C:\Folder\SubFolder
VAV.$$LOG=Test 3 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 3 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 4: ACH with backslash, Last occurrence (-1), Target $$OUT
VAV.$$SRC=C:\Folder\SubFolder\File.txt
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 4: ACH ($$SRC='$$SRC') with '\', Index=-1, Target=$$OUT (expecting 'File.txt')$crlf$
PRT.$$LOG
ACH.$$SRC|\|-1|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=File.txt
VAV.$$LOG=Test 4 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 4 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' --- Specific Index Cases (Using $pip$) ---
' Test 5: BCH Nth Positive Index (3rd '|')
VAV.$$SRC=A|B|C|D|E
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 5: BCH ($$SRC='$$SRC') with '$pip$' (pipe), Index=3, Target=$$OUT (expecting 'A|B|C')$crlf$
PRT.$$LOG
' Use $pip$ as delimiter
BCH.$$SRC|$pip$|3|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=A|B|C
VAV.$$LOG=Test 5 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 5 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 6: ACH Nth Positive Index (3rd '|')
VAV.$$SRC=A|B|C|D|E
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 6: ACH ($$SRC='$$SRC') with '$pip$' (pipe), Index=3, Target=$$OUT (expecting 'D|E')$crlf$
PRT.$$LOG
' Use $pip$ as delimiter
ACH.$$SRC|$pip$|3|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=D|E
VAV.$$LOG=Test 6 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 6 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 7: BCH Nth Negative Index (2nd '|' from right)
VAV.$$SRC=A|B|C|D|E
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 7: BCH ($$SRC='$$SRC') with '$pip$' (pipe), Index=-2, Target=$$OUT (expecting 'A|B|C|D')$crlf$
PRT.$$LOG
' Use $pip$ as delimiter
BCH.$$SRC|$pip$|-2|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=A|B|C|D
VAV.$$LOG=Test 7 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 7 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 8: ACH Nth Negative Index (2nd '|' from right)
VAV.$$SRC=A|B|C|D|E
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 8: ACH ($$SRC='$$SRC') with '$pip$' (pipe), Index=-2, Target=$$OUT (expecting 'E')$crlf$
PRT.$$LOG
' Use $pip$ as delimiter
ACH.$$SRC|$pip$|-2|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=E
VAV.$$LOG=Test 8 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 8 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' --- Edge Cases ---
' Test 9: Delimiter Not Found
VAV.$$SRC=NoDelimitersHere
' Use simple known value for unchanged check
VAV.$$OUT=$$FIX
VAV.$$LOG=Test 9: BCH ($$SRC='$$SRC') with 'X', Index=1, Target=$$OUT (expecting $$OUT unchanged)$crlf$
PRT.$$LOG
BCH.$$SRC|X|1|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
' Simplified IVS check
IVS.$$OUT=$$FIX
VAV.$$LOG=Test 9 Passed (Result unchanged)$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 9 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 10: Index Out of Bounds (Positive, using $pip$)
VAV.$$SRC=A|B
VAV.$$OUT=$$FIX
VAV.$$LOG=Test 10: BCH ($$SRC='$$SRC') with '$pip$' (pipe), Index=5, Target=$$OUT (expecting $$OUT unchanged)$crlf$
PRT.$$LOG
' Use $pip$ as delimiter
BCH.$$SRC|$pip$|5|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=$$FIX
VAV.$$LOG=Test 10 Passed (Result unchanged)$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 10 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 11: Index Out of Bounds (Negative, using $pip$)
VAV.$$SRC=A|B
VAV.$$OUT=$$FIX
VAV.$$LOG=Test 11: ACH ($$SRC='$$SRC') with '$pip$' (pipe), Index=-5, Target=$$OUT (expecting $$OUT unchanged)$crlf$
PRT.$$LOG
' Use $pip$ as delimiter
ACH.$$SRC|$pip$|-5|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=$$FIX
VAV.$$LOG=Test 11 Passed (Result unchanged)$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 11 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' --- $TOS Target Cases (Original intention, using POP) ---
' Test 12: Targeting $TOS (3 Params - Index omitted, defaults to 1)
VAV.$$SRC=UseTOS.txt
VAV.$$OUT=ClearRes
VAV.$$LOG=Test 12: BCH ($$SRC='$$SRC') with '.', Target=$TOS (3 params) (expecting 'UseTOS')$crlf$
PRT.$$LOG
' P1 | P2 - Implies P3=1, P4=$TOS
BCH.$$SRC|.
' Get result from $TOS into $$OUT
POP.$$OUT
VAV.$$LOG=Result (from POP): $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=UseTOS
VAV.$$LOG=Test 12 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 12 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 13: Targeting $TOS (4 Params, Empty P4)
VAV.$$SRC=UseTOS_EmptyP4.log
VAV.$$OUT=ClearRes
VAV.$$LOG=Test 13: ACH ($$SRC='$$SRC') with '.', Index=1, Target=Empty (use $TOS) (expecting 'log')$crlf$
PRT.$$LOG
' P1 | P2 | P3 | P4 (empty) -> should use $TOS
ACH.$$SRC|.|1|
' Get result from $TOS into $$OUT
POP.$$OUT
VAV.$$LOG=Result (from POP): $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=log
VAV.$$LOG=Test 13 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 13 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' --- More Edge Cases ---
' Test 14: Delimiter at Start
VAV.$$SRC=.start
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 14: ACH ($$SRC='$$SRC') with '.', Index=1, Target=$$OUT (expecting 'start')$crlf$
PRT.$$LOG
ACH.$$SRC|.|1|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=start
VAV.$$LOG=Test 14 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 14 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' Test 15: Delimiter at End
VAV.$$SRC=end.
VAV.$$OUT=InitialValue
VAV.$$LOG=Test 15: BCH ($$SRC='$$SRC') with '.', Index=-1, Target=$$OUT (expecting 'end')$crlf$
PRT.$$LOG
BCH.$$SRC|.|-1|$$OUT
VAV.$$LOG=Result: $$OUT$crlf$
PRT.$$LOG
IVS.$$OUT=end
VAV.$$LOG=Test 15 Passed$crlf$
PRT.$$LOG
ELS.
VAV.$$LOG=Test 15 Failed$crlf$Got '$$OUT'
PRT.$$LOG
EIF.
' --- Test Suite End ---
VAV.$$LOG=$crlf$=== Validated Variable Test Suite Finished (using $pip$) ===$crlf$
PRT.$$LOG
MBX.!
' End script
ENR.
'===========================================================
See also: