Editing mirc/identifiers/$findfile

{{mirc title|$findfile Identifier}}'''$findfile''' Searches the specified directory (and optionally its subdirectories) for the Nth filename matching the wildcard file specification and returns the full path and filename if it is found.
== Synopsis ==
<pre>$findfile(dir, wildcard , N , [depth , [@window | command] ] )</pre>

== Parameters ==
* '''DIR''' - Name of the starting folder name.
* '''wildcard''' - Filename being searched for. Can be filename or wildcard(s).
* '''N''' - Nth sequential file being searched for. 0 is count of ALL files.
* '''depth''' - optional folder depth, counting DIR as the first level. 0 or 1 is DIR level only. If depth not used, there's no depth limit.
* '''command''' - optional 5th parameter. Can use $findfilen as the sequential number for that filename, or $1- for the space-delimited filename.
* '''@window''' - optional 5th parameter. Must be window with side listbox created with -l2 switch. Each $1- from matching filenames is appended as a new line to the side listbox. Is equivalent to: /aline -la @window $1-

Note: DIR can be absolute \path or c:\path or relative to $mircdir. Does not need ending slash. Accepts forward/backward slashes interchangeably but always output backslash.

Note: More than 1 filename or wildcard can be used by delimiting them with a ; semi-colon. *.* returns filenames without a file extension. Filenames matching the 1st wildcard are returned prior to those matching the 2nd wildcard. Filenames matching more than 1 wildcard will not return more than once. After removing duplicates, files are returned recursively in alphabetical order.

Note: Aliased folders can cause the same file to be returned within multiple folder names.

Note: $findfile using the 5th parameter to append lines to a @window side listbox or run commands should not be run as the first command on a scriptline because it also outputs either the N=0 filecount (even 0) or the N>0 filename - likely generating an invalid command error. Instead, begin the command with /noop or /var %dummyvariable. The @window and /command alternatives must be the 5th parameter, so depth is required when using them.
== Properties ==
* '''shortfn''' - causes N > 0 or $1- within 5th parameter to return short filenames and/or foldernames when a case-insensitive evaluation of the filename is not a valid DOS filename. (Invalid characters, more than 1 period, filename prefix longer than 8, file extension longer than 4, etc)

Note: Returned string can contain multiple consecutive spaces if the file/folder names contain them, causing $file() and other mIRC identifiers to fail. This problem can be avoided by using .shortfn which never contains any spaces.

== Example ==
<source lang="mIRC">
//noop $findfile( c:\program files\, * ,0,2,echo -s $ord($findfilen) $1-).shortfn
  echoes all filenames in c:\program files\ and 1 level beneath it. .shortfn causes all foldernames and pathnames to be converted to short filenames if necessary. The "Program Files" folder appears as PROGRA~1 regardless of the way it was spelled for DIR.
//noop //echo -a $findfile( c:\proGra~1\, * ,0,2,echo -s $ord($findfilen) $1-)
  same, except the "Program Files" folder is displayed exactly as spelled for DIR.
</source>

<source lang="mIRC">
//window @FileList | var %a $findfile( $sysdir(downloads),*.jpg;*.png;w* ,0,1,@FileList1)
  Loads path\filenames of files in windows username's download folder (not necessarily mIRC's download folder) but nothing from any subfolders beneath it. The list will be an alphabetical list of all *.jpg followed by all *.jpg followed by all filenames beginning with W which did not match the prior wildcards.
</source>

<source lang="mIRC">
//echo -a Versions.txt $iif($findfile($mircdir,versions.txt,1,1),is,isn't) in the same folder as $nopath($mircini)

//echo -a $findfile( $sysdir(profile),*.html,0,999,echo -s $iif($!isfile($1), There are multiple consecutive spaces in the folder\filename $1-))
  Multiple consecutive spaces in folder/file names can cause $file($1-).size to either fail to see an existing file or incorrectly see a similarly named filename without the extra spaces.
</source>

<source lang="mIRC">
DIR can be relative path to $mircdir. \windows\ is relative to the root folder on the same drive letter where $mircdir is. If $getdir is the downloads subfolder of $mircdir, which is c:\mIRC\, the following pair of commands return the same list of files, with the only difference being that mIRC displays the same spelling of the portion of the path entered as the DIR parameter. This means that while they both incorrectly capitalize the W in downloads, the 1st one shows the true c:\mIRC\ spelling while the 2nd one displays as the lower case used in the  DIR parameter.

//echo -a $findfile(doWnloads,* ,0,2,echo -s $1- )
//echo -a $findfile(c:\mirc748\doWnloads,* ,0,2,echo -s $1- )

Because relative path can include the .. alias for the parent folder, both following examples show all filenames in the c:\ root folder, differing only by the DIR string used in the example:

//echo -a $findfile(c:\No Such Folder\..\,*,0,1,echo -s $1- )
//echo -a $findfile( $getdir $+ $str(..\,$calc($numtok($getdir,92) -1)) ,*,0,1,echo -s $1- )

(Even though c:\No Such Folder\ does not exist, appending the ..\ starts with c:\ which does exist.)
</source>
== Compatibility ==
{{mIRC compatibility|4.7}}

== See Also ==
{{collist
|count = 4
|style = width: 100%; display: inherit;
|
* {{mIRC|$finddir}}
* {{mIRC|$findfilen}}
* {{mIRC|$shortfn}}
* {{mIRC|$sysdir}}
* {{mIRC|$mircdir}}
* {{mIRC|$getdir}}
}}
[[Category:mIRC identifiers|$didtok]]