PJO. - Path Join |
Previous (GPP.) Top Next |
MiniRobotLanguage (MRL)
PJO. Command
Path Join Operation
Intention
PJO. intelligently joins multiple string segments to create a single, correctly formatted file path string, storing the result in a specified variable or on the stack.
It automatically handles adding or removing backslash (\) separators between segments to avoid missing or double separators. It also correctly handles absolute paths appearing in later segments and allows control over the final trailing slash.
Usage:
' Will concat the Pathes $$PAA and $$PAB and prevent a "\" at the end of the result in $$RES
PJO.noslash|$$RES|$$PAA|$$PAB
MBX.$$RES
ENR.
Syntax
PJO.[Modifiers]|OutputTarget|Segment1|Segment2[|Segment3...]
Parameter Explanation
Parameter 1: [Modifiers] or Segment1
·If this parameter contains the keywords forceslash or noslash (case-insensitive, comma-separated if needed, though usually only one applies), it's treated as modifiers affecting the final result.forceslash: Ensures the final joined path ends with a trailing backslash (\). Mutually exclusive with noslash.
·noslash: Ensures the final joined path does *not* end with a trailing backslash (\). Mutually exclusive with forceslash.
Parameter 2: OutputTarget (Mandatory)
·Must be either a hyphen (-) to indicate the result should be placed on the Top-Of-Stack (TOS)...
·...OR a valid variable name in the format $$xxx (e.g., $$PAT, $$RES) where the result will be stored.
Parameter 3 onwards: Segment1, Segment2 ...
·These are the path segments to join. They start at Parameter 3 if Parameter 1 contained modifiers, or they start at Parameter 1 if Parameter 1 did not contain modifiers (in which case Parameter 3 is actually Segment2).
·Segments can be literal strings or variables (e.g., $$ABC). Variables used as segments will have their content resolved before joining.
·At least one segment must follow the OutputTarget parameter.
Behavior Details
·Separator Handling: A single backslash (\) is automatically inserted between segments unless one is already present at the join point (e.g., PJO.|-|C:\Path|\Sub yields C:\Path\Sub).
·Absolute Path Reset: If any segment *after the first actual segment* starts with a drive letter and colon (D:), a UNC prefix (\\), or a root backslash (\), it is treated as an absolute path. Any previously joined segments are discarded, and the path construction restarts from this absolute segment.
·Empty Segments: Segments that are empty or contain only whitespace are ignored during the join process.
Comprehensive Example
The following example demonstrates various uses of the PJO.
VAR.$$DRV=C:
VAR.$$FL1=Windows
VAR.$$FL2=System32\
VAR.$$FNM=kernel32.dll
VAR.$$USR=Users\Test
VAR.$$ABS=D:\Data
VAR.$$SHR=\\Server\Share
VAR.$$EMP=
VAR.$$SUB=SubFolder
PRT.--- Basic Joining to Variable ---
PJO.|$$RES|$$DRV|$$FL1|$$FL2|$$FNM
PRT.Result 1 (to $$RES): $$RES
PRT.--- Basic Joining to TOS ---
PJO.|-|$$DRV|$$FL1|\details.txt
POP.$$TOS
PRT.Result 2 (to TOS): $$TOS
PRT.--- Using forceslash Modifier ---
PJO.forceslash|$$RS3|$$DRV|$$USR
PRT.Result 3 (forceslash): $$RS3
PRT.--- Using noslash Modifier ---
PJO.noslash|$$RS4|$$DRV|$$FL1|$$FL2
PRT.Result 4 (noslash): $$RS4
PRT.--- Absolute Path Reset ---
PJO.|$$RS5|$$DRV|$$USR|$$ABS|\log.txt
PRT.Result 5 (absolute reset): $$RS5
PRT.--- Ignoring Empty Segment ---
PJO.|$$RS6|$$DRV|$$FL1|$$EMP|$$FL2|$$FNM
PRT.Result 6 (empty ignored): $$RS6
PRT.--- UNC Path Example ---
PJO.|$$RS7|$$SHR|Data|backup.zip
PRT.Result 7 (UNC): $$RS7
PRT.--- Relative from Root ---
PJO.|$$RS8|\Program Files|My App|settings.ini
PRT.Result 8 (root relative): $$RS8
PRT.--- Using Variable as Segment ---
PJO.|$$RS9|$$DRV|$$USR|$$SUB|file.dat
PRT.Result 9 (Var Segment): $$RS9
MBX.PJO Demo Complete!
END.
Remarks
·The OutputTarget (Parameter 2) is mandatory. Use - to send the result to the stack (TOS).
·This command is useful for constructing paths dynamically from variables or fixed strings.
·Modifiers in the optional first parameter are case-insensitive.
·The command does not simplify paths (e.g., resolve `.` or `..` segments) or validate if the path exists.
·The forceslash and noslash modifiers are mutually exclusive.
Limitations:
·The maximum number of segments plus other parameters is limited by the internal parameter splitting mechanism (typically around 39 total parameters).
·Variable names used for the OutputTarget must follow the $$xxx format (exactly three characters after $$).
See also:
• 1.5.2 Working with Text-Strings