UPath                       AUTOHOTKEY FUNCTION                      MANUAL PAGE

_NAME_
UPath - More than unix like accessing files and folders

_SYNTAX_
UPath(Path, [Options], [RegExFilter])
UPath("Path [|| RegExFilter]", "[-qfdSas{e|E}H]", "[RegExFilter]")

_DESCRIPTION_
UPath gets from an Unix like file address the Windows absolute path, but it
do more than that. Relative addresses, wildcards ("*" and "?") and the "." and
".." will be extended also. On default, system files and folders don't exist to
UPath.
The first parameter is required and expects an Unix like path. There are some
special keys at the first character of the path string. If the path begins with
a slash ("/"), then the scripts root drive will be used (portable). A double
slash ("//") means the scripts own directory (portable). A "~" means the home of
current user. This is the computers local MyDocuments folder of current logged
on user (non portable). Starting path with an absolute Windows notation (this is
if drive letter followed by a doublecolon ":", for example "D:") will be leaved
as is.
The second parameter is not required and defines some options described below in
OPTIONS section.
The third parameter is a regular expression filter. Any filter matching the path
will be found, otherwise it does not exist to UPath. The comparison is never
case sensitive. Also the Path itself can contain the regular expression filter,
separated by a " || " (note the required spaces around the separator!).

On every existing file or folder that match, 1 (in word "one") will be added
to global variable ErrorLevel@UPath. At the end, it will contain logically the
count of all matches (0 if not exists).

Example 1
Script := UPath("/bin/Scripts/Scriptname.ahk")
If ErrorLevel@UPath
    Run, %Script%

Example 2
Path := UPath("../*UPath*", "--all --subdirs")

Example 3
Path := UPath("* || \.(ahk|au3)$")

_OPTIONS_
A space separated string of optional options. Every single option must start
with a dash "-" (like Unix) or a slash "/" (like Windows). Long format like in
Unix/Linux starting with two dashes and following an easy to remember word is
also possible. Short grouping style is possible also. You can type for example
"-fas" instead of "-f -a -s". You could even write "-f -as" or the long format
"--file --all --subdirs"! It`s up to you, which style you want to use.

Comparison is case sensitive! An "s" is not equal to "S"!!

-q or --quot        = Every path (existing or not, it does not matter) will be
                      enclosed between double quotes, even on --all option.
-f or --file        = Operate and get files only. No search on folders.
-d or --dir         = Operate and get folders only. No search on files.

If both, -f and -d are specified together or nothing, then it defaults to files
AND folders.

-S or --system      = Include files and folders with system attribute. (default
                      behaviour is excluding them)
-a or --all         = Get all founded items as a semicolon separated list.
                      (Makes only sense with wildcards.)
-s or --subdirs     = Searches also in all subdirectories. (Be careful,
                      result may not be accurate, see at BUGS section)
-e or --env         = Searches in the system environment PATH. But First the
                      current WorkingDir of script will be searched.
-E or --envonly     = Searches in the system environment PATH without current
                      WorkingDir.

If both, -e and -E are specified together, then -E have a higher priority and
will be used instead of -e.

-H or --high        = Use more system resources.  Current script BatchLines
                      will be affected during UPath and scripts priority set to
                      high. Before return to script from UPath function, the
                      priority will be set to normal (no matter what it was
                      before! I need some help on this: How can I get scripts
                      actual priority level?).

_RETURN_
The converted full path of a Windows file or directory will be returned. If
path exists, then case correction to that one saved on the disk will be done
automatically also. On using wildcards and the --all option together, a comma
separated list of founded paths will be returned. The string will be empty, if
any wildcard is used and search string is not found. Also if the --quot option
is given, every path is packed in double quotes.


_CALLS_
* External Function GetPathFromLoop@UPath
* External Function AddDirectoryTail@UPath
* External Function SubDirectoryTail@UPath
* External Function SubFirstChar@UPath
* External Function AddQuotes@UPath
* External Function IsAbsolute@UPath
* External Function GetRegExInPathPosition@UPath
* Internal Subroutine SetOptions@UPath
* Internal Subroutine SetRegEx@UPath

_FILES_
There is no need of any external file to work with UPath and nothing will be
created.

_BUGS_
There is a limitation on searching subdirectories (-s). The subdirectory must
have the search string given in Path. This can be worked around by using only
wildcards in Path and regular expression to filter them out, because all
subdirectories would be searched in that case. The disadvantages of regex is,
it's very slow and complicated to get work correctly.


_AUTHOR_
Tuncay <tuncay.d@gmx.net>