PathX() : Split & modify a filepath easily

[SKAN]

PathX() is an alternative solution for SplitPath command. It breaks down a fullpath to individual parts and returns them as an associative array. Note that the results from PathX() will be different from SplitPath command. The common reason a filepath is split is to concatenate them back again to form a different filepath. PathX() can do this in one go. Custom key values can be provided as variadic parameters to substitute individual parts of the returned array.

PathX() is powered by two API functions

1) GetFullPathName (kernel32.dll): To pre-process the filepath into a clean fullpath.
2) _wsplitpath (msvcrt.dll): To break down a full filepath into 4 parts.

GetFullPathName (kernel32.dll):
The path passed to the function will be converted to a full path unconditionally. If only a filename is passed, it will be resolved to a full path by prefixing the filename with A_WorkingDir. Any relative path will be converted to full path. For example: A_AhkPath . "\..\License.txt" would be converted to "C:\Program Files\AutoHotkey\License.txt" (assuming you did a default install.). If you are passing a fullpath, the first two chars must be a proper drive letter.. means if you pass a path like a file:/// URL, then it will be unconditionally prefixed with A_WorkingDir. GetFullPathName() will also clean up the filepath. It will convert any forward slashes present in filepath to back slashes and then remove any redundant ones. For eg. D:\/Folder\/\/\\\\file.ext will be cleaned up to D:\Folder\file.ext before it is split into parts. GetFullPathName() will fail if null filepath is passed or filepath is longer than MAX_PATH (260 TChars)

_wsplitpath (msvcrt.dll)
This function breaks down a filepath differently when compared to the output of SplitPath command. It splits a filepath into 4 parts (red/blue/red/blue) as follows:
Example path: C:\Program Files\AutoHotkey\AutoHotkey.exe

Code: Select all

C:                              ; Drive - first 2 chars 
\Program Files\AutoHotkey\      ; Dir   - Every thing after first colon up till the last slash (last slash will be included)
AutoHotkey                      ; Fname - Every thing in between last slash and last period  
.exe                            ; Ext   - The last period and every thing after it

If anyone wants to test and validate my above statements, use two colons :: after drive letter as well as multiple slashes before the filename.
Then one can easily see how _wsplipath() does the chop chop.
_wsplitpath() will fail in any of the individual filepath part exceeds MAX_PATH (260 TChars).

The array returned by PathX() will contain all the four parts namely Drive, Dir, Fname, Ext. and additionally: Folder (Drive+Dir), File (Fname+Ext) and Full (Drive+Dir+Fname+Ext). The reason for returning the fullpath is that PathX() accepts variadic parameters through which any or 3 of the filepath parts can be replaced with new values. The Full key (in returned array) will contain the modified filepath as value.

---

PathX(Filepath, [Variadic parameters]).
PathX() splits a filepath and returns filepath parts as an associative array with following keys:

• 1) Drive
• 2) Dir
• 3) Fname (Filename without extension)
• 4) Ext
• 5) Folder (Concatenation of 1 & 2)
• 6) File (Concatenation of 3 & 4)
• 7) Full (Concatenation of 1,2,3 & 4)

Try the following example to see the key value pairs of the array returned:

Code: Select all

Px := PathX(A_AhkPath)

Msgbox,,  Key and values, % "" 
       . "Drive`t:`t"  . Px.Drive  "`n"
       . "Dir`t:`t"    . Px.Dir    "`n"
       . "Fname`t:`t"  . Px.fname  "`n"
       . "Ext`t:`t"    . Px.Ext    "`n"                 
       . "Folder`t:`t" . Px.Folder "`n"                 
       . "File`t:`t"   . Px.File   "`n"                 
       . "Full`t:`t"   . Px.Full

The first 4 keys Drive, Dir, Fname and Ext can be overwritten with custom values:

Code: Select all

MsgBox,, Change name,         % PathX(A_ScriptName, "Fname:Hello World").Full
MsgBox,, Change drive,        % PathX(A_ScriptName, "Drive:Z:").Full
MsgBox,, Change path to root, % PathX(A_ScriptName, "Dir:\").Full
MsgBox,, Change extension,    % PathX(A_ScriptName, "Ext:.txt").Full

Added in v0.67: _Ext key. See example

PathX() will resolve relative path to fullpath unconditionally:

Code: Select all

MsgBox,, One level up,        % PathX("\..\" . A_ScriptName).Full
MsgBox,, Two levels down, % PathX("Sub_folder\Sub_folder\" A_ScriptName).Full

One may pass multiple parameters as well as shorten the key names to two chars:
The following example shows how to substitute Drive and Fname in one go.
Note: Make sure there are no spaces between Key:Value unless it was intended.

Code: Select all

MsgBox,, New path, % PathX(A_ScriptName, "Dr:X:", "Fn:MyScript").Full

Keys Fprefix and Fsuffix can be used to add prefix/suffix to Fname

Code: Select all

MsgBox,, Prefix Fname,  % PathX(A_ScriptName, "fp:Copy of ").Full
MsgBox,, Suffix Fname,  % PathX(A_ScriptName, "fs:_001").Full
MsgBox,, Prefix/Suffix, % PathX(A_ScriptName, "fp:Backup_", "fs:" . "_" . A_Now).Full

Additional file extension can be kind of prefixed indirectly by suffixing Fname:

Code: Select all

MsgBox,, Prefix extension,  % PathX(A_AhkPath, "fs:.old").Full

Keys Dprefix and Dsuffix may be used to add prefix/suffix to Dir

Code: Select all

MsgBox,, Prefix/Suffix Dir,  % PathX(A_ScriptName, "Dr:N:", "Dp:\Backup", "Ds:001\").Full

Added in v0.66:
Keys Pprefix and Psuffix may be used to add prefix/suffix to Fullpath

Code: Select all

MsgBox,, Prefix fullpath,  % PathX(A_ScriptName, "pp:file:///").Full
MsgBox,, Prefix fullpath,  % PathX(A_ScriptName, "pp:\\?\").Full
MsgBox,, Suffix ADS name,  % PathX(A_ScriptName, "ps::HiddenData").Full

Within Loop, Files, A_LoopFileName is available but no built-in var for base file name (file name without extension).
PathX() can be used as follows:

Code: Select all

Loop Files, %A_AhkPath%\..\*.exe
  MsgBox % PathX(A_LoopFileLongPath).FName

---

The function:

Code: Select all

PathX(S, P*) {                                ; PathX v0.67 by SKAN on D34U/D35I @ tiny.cc/pathx
Local K,V,N,  U:={},   T:=Format(A_IsUnicode ? "{1:260}" : "{1:520}", ""),   dr:=di:=fn:=ex := T
  For K,V in P
      N := StrSplit(V,":",,2),  K := SubStr(N[1],1,2),  U[K] := N[2]
  DllCall("GetFullPathName", "Str",Trim(S,Chr(34)), "UInt",260, "Str",T, "Ptr",0)
  DllCall("msvcrt\_wsplitpath", "WStr",T, "WStr",dr, "WStr",di, "WStr",fn, "WStr",ex)
Return {"Drive":dr:=u.dr?u.dr:dr,"Dir":di:=(u.dp)(u.di=""?di:u.di)(u.ds),"Fname":fn:=(u.fp)(u.fn
     =""?fn:u.fn)(u.fs),"Ext":ex:=u._e!=""?(ex?ex:u._e):u.ex=""?ex:u.ex,"Folder":(dr)(di),"File"
     :(fn)(ex),"Full":(u.pp)(dr)(di)(fn)(ex)(u.ps) }
}

The function - Readable version

Code: Select all

PathX(S, P*) {                                ; PathX v0.67 by SKAN on D34U/D35I @ tiny.cc/pathx
Local K,V,N,  U:={},   T:=Format(A_IsUnicode ? "{1:260}" : "{1:520}", ""),   dr:=di:=fn:=ex := T

  For K,V in P
      N := StrSplit(V,":",,2),  K := SubStr(N[1],1,2),  U[K] := N[2]

  DllCall("GetFullPathName", "Str",Trim(S,Chr(34)), "UInt",260, "Str",T, "Ptr",0)
  DllCall("msvcrt\_wsplitpath", "WStr",T, "WStr",dr, "WStr",di, "WStr",fn, "WStr",ex)

Return { "Drive"  : dr := u.dr ? u.dr : dr 
       , "Dir"    : di := (u.dp) (u.di="" ? di : u.di) (u.ds) 
       , "Fname"  : fn := (u.fp) (u.fn="" ? fn : u.fn) (u.fs)     
       , "Ext"    : ex := u._e!="" ? (ex ? ex : u._e) : u.ex="" ? ex : u.ex        
       , "Folder" : (dr) (di)
       , "File"   : (fn) (ex)
       , "Full"   : (u.pp) (dr) (di) (fn) (ex) (u.ps) }
}

[toralf]

That is a cool idea/script. Will come handy. Thanks for sharing

[SKAN]

Thanks dear toralf

[burque505]

What a useful function - thank you! And, as always, your documentation and examples are great.
Regards,
burque505

[SKAN]

What a useful function - thank you! And, as always, your documentation and examples are great.

Thanks for the feedback

Just added one more example:


Within Loop, Files, A_LoopFileName is available but no built-in var for base file name (file name without extension).
PathX() can be used as follows:

Code: Select all

Loop Files, %A_AhkPath%\..\*.exe
  MsgBox % PathX(A_LoopFileLongPath).FName

[ozzii]

Like always, very great function and examples.
Thank you

[SKAN]

@ozzii

[Helgef]

If a function needs to access or create a large number of global variables, it can be defined to assume that all its variables are global (except its parameters) by making its first line either the word "global" or the declaration of a local variable.

My bold. Meaning that if you forget to declare one, it is assumed to be global. See,

Code: Select all

#include pathx.ahk
listvars
msgbox

I recommend you do

Code: Select all

pathx(...) {
	local
	; ...
}

Cheers, and thanks for sharing.

[SKAN]

if you forget to declare one, it is assumed to be global.

Yes, I know... somehow I missed. I usually call ListVars within the function to see which is where.
I need a haircut badly

Cheers, and thanks for sharing.

Thanks for caring. You're an invaluable asset to this community!


Code updated: Fixed local variables leaking into Global space

[SirSocks]

This is great! The examples are excellent! Thank you very much.

[SKAN]

@SirSocks

[SKAN]

Code: Select all

/*
Code updated : v0.66
Keys Pprefix and Psuffix may be used to add prefix/suffix to Fullpath
*/

MsgBox,, Prefix fullpath,  % PathX(A_ScriptName, "pp:file:///").Full
MsgBox,, Prefix fullpath,  % PathX(A_ScriptName, "pp:\\?\").Full
MsgBox,, Suffix ADS name,  % PathX(A_ScriptName, "ps::HiddenData").Full

[SKAN]

Bug fix:
I was tring to rename a file to 0.0 with PathX(File, "Fn:0", "Ext:.0"), but function was returning filepath intact
since both 0 and .0 evaluates to false. Fixed code to check if keys are blank instead of evaluating a true.

New in 0.67

File extension can be forced with Ext key for File save dialog

Code: Select all

FileSelectFile, sFile, S2, %A_ScriptDir%, Save file, *.txt
If not (ErrorLevel)
   Msgbox % sFile := PathX(sFile, "ext:.txt").Full  ; extension .txt is enforced

Now added a _Ext key that will add extension only if not already present

Code: Select all

FileSelectFile, sFile, S2, %A_ScriptDir%, Save file, *.*
If not (ErrorLevel)
   Msgbox % sFile := PathX(sFile, "_ext:.txt").Full ; .txt is appended only if user doesn't specify any

[jetrotal]

@SKAN

One suggestion:
If we use pathX function on a folder

Code: Select all

pathX("C:\ My files")

fill the Fname with the folder name.

now it returns "", but it could return "My files".

[Mika_erdo]

SKAN you is the man.
Much appreciated