*! version 1.1 16 October 2018
help for filesearch version 1.1 (16 October 2018)

Title

filesearch -- recursively list files matching to a pattern or regular expression

Table of contents

Syntax
Description
Options
Remarks
Examples
Author
Saved results
Also see

Syntax

filesearch [[`]"]pattern["[']] [, options]

Note: If pattern contains at least one comma, it has to be enclosed in double quotes.

If pattern contains double quotes, it has to be enclosed in compound double quotes (see help quotes).

Searching
subdirectories search for subdirectory names instead of filenames

directory(directory) search in directory

recursive recursive search in subdirectories

maxdepth(num) descend no more than num levels into subdirectories in recursive search

regexpression pattern is to be interpreted as regular expression

Output
fullpath return full file paths (instead of relative ones)

noquote don't enclose results with double quotes

quiet suppress displaying (non-error) output

strip remove pattern from result

local(macname) return result in local macname instead of r(filenames)

Description

filesearch (recursively) reads file- or subdirectory names from a filesystem directory.It can filter results by string match patterns or regular expressions.
It is quite similar to the popular fs by Nicholas J. Cox, but adds additional capabilites.

The most prominent additions are:

- case sensitive search even on Windows operating systems

- recursive search

- search using regular expressions instead of "simple" string matching patterns

Options

Searching

subdirectories if specified, search for subdirectory names instead of filenames.

directory(directory) if specified, search for the results inside directory. If omitted, the working directory is used.

If directory(directory) is specified but directory is not accessible or does not exist, the working directory is used instead and a warning message is displayed.

recursive if specified, the search is performed recursively throughout subdirectories in the specified directory.

maxdepth(num) implies recursive; if specified, recursive search will descend no more than num levels of subdirectories.

num has to be a integer value greater or equal to 0, or the system missing value (leading to indefinite descent through subdirectores).

regexpression if specified, pattern will be treated as regular expression.filesearch will use Stata's regular expression engine to filter the results list.
Information about regular expressions can be found on the internet, and in Stata's help and FAQ about the topic.

Output

fullpath if specified, search results will contain the full path (including directory).

noquote if specified, search results will not be quoted. Default is to enclose each result in double quotes.

quiet if specified, search results will not be displayed (but returned in r()).
Warning messages, if any, will be displayed anyways

local(macname) if specified, return search results to the local macro macname instead of r().

The local macro macname will be overwritten without warning.

strip if specified, remove the string part that matches pattern from the output.

Remarks

It is recommended that even if you use Windows,you use forward slashes (/) rather than backward slashes (\) for specifying directory names.Stata will understand and there will then be no clash with other meanings for the backward slash.

This command is part of the NEPmgmt bundle, written to help creating the NEPS dataset files.

The source code of the program is licensed under the GNU General Public License version 3 or later.The corresponding license text can be found on the internet at http://www.gnu.org/licenses/ or in gnugpl.

filesearch is the successor to an older command, retrievefilenames, which is now deprecated.

Users of retrievefilenames are encouraged to migrate their syntax.The following table presents aid for translating your syntax:

retrievefilenames syntax --> filesearch syntax equivalent

retrievefilenames --> filesearch *

retrievefilenames, filedirectory(dirname) --> filesearch *, directory(dirname)

retrievefilenames, subdirectories --> filesearch *, subdirectories

retrievefilenames, extension(dta) --> filesearch *.dta

retrievefilenames, searchexpression(\.(dta)|(DTA)$) --> filesearch \.(dta)|(DTA)$, regexpression

retrievefilenames, extension(dta) local(filelist) --> filesearch *.dta, local(filelist)

retrievefilenames, extension(dta) strip --> filesearch \.dta$, regexpression strip

Examples

Get all filenames from working directory:

. filesearch *

Get all names of subdirectories from working directory:

. filesearch *, subdirectories

Find all files ending with ".txt" in working directory:

. filesearch *.txt

Retrieve filenames ending with ".txt" from directory /home/user/Desktop and remove ".txt" from output:

. filesearch \.txt$, directory(/home/user/Desktop) regexpression strip

Do the same, put suppress displaying the results:

. filesearch \.txt$, directory(/home/user/Desktop) regexpression strip quiet

Recursively search all files ending with ".txt" in all subdirectories of /home/user/Desktop,and return their full path names:

. filesearch *.txt, directory(/home/user/Desktop) recursive fullpath

Author

Daniel Bela (daniel.bela@lifbi.de), Leibniz Institute for Educational Trajectories (LIfBi), Germany.

Saved results

filesearch saves the following in r():

Locals

r(filenames) filenames that match the search pattern

or

r(dirnames) subdirectory names retrieved that match the search pattern (if option subdirectories is specified)

or

nothing , if option local() is specified

Also see

Help: NEPSmgmt, ls, [F] f_regexm, http://www.stata.com/support/faqs/data/regex.html