*! version 1.6 14 September 2018
help for retrievefilenames version 1.6 (14 September 2018)

Thanks for using retrievefilenames. Please note: This program is deprecated in favor of its more flexible successor, filesearch.

filesearch is available from SSC, or from LIfBi's self-operated Stata repository.

Please consider migrating your syntax to filesearch. The help file for filesearch can help (if installed).

This help file still exists for archival purposes only; as retrievefilenames itself, it will not receive updates any more.

Title

retrievefilenames -- retrieve filenames from filesystem directory

Table of contents

Syntax
Description
Options
Remarks
Examples
Author
Saved results
Also see

Syntax

retrievefilenames [, options]

Searching
extension(ext) retrieve filenames ending with ext

subdirectories retrieve directory names instead of filenames

filedir(directory) retrieve filenames from directory

searchexpression(regex) only retrieve filenames matching regex

Advanced
local(macname) return result in local macname

strip remove string matching regex from result

Description

retrievefilenames reads file- or directory names from a filesystem directory. It can filter results by filename extensions or regular expressions, and remove the search pattern from search results.

It is quite similar to the popular fs, but accounts for its shortcomigs like the lack of case sensitivity and extensive filtering of results.

Options

Searching

extension(ext) if specified, retrieve filenames ending with ext only.

Note that ext should not contain a leading period, and should not be enclosed in (compound) double quotes.

This option is a simple shortcut to searchexpression(\.ext$). Thus it collides with searchexpression(string), and the latter is ignored (and a warning message is triggered) if both are specified.

If both are not specified, all filenames are retrieved.

subdirectories if specified, retrieve names of subdirectories instead of filenames.

filedirectory(directory) if specified, retrieve the filenames inside directory. If not specified, the working directory is used.

Note that directory should not contain a trailing slash, and should not be enclosed in (compound) double quotes.

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

searchexpression(regex) if specified, retrieve filenames matching regex only. regex has to be a regular expression, as documented in the Stata help and FAQ.

If not specified (and not implicitly specified via extension(ext)), all filenames are retrieved.

Advanced

local(macname) if specified, save search results to the local macro macname (in addition to the saved results).

strip if specified, remove the string matching regex, as specified in searchexpression(regex) (or ext as specified in extension(ext)), from the output.

If none of searchexpression(regex) or extension(ext) is specified, strip is ignored and a warning message is triggered.

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.

Examples

Retrieve all filenames from working directory:

. retrievefilenames

Retrieve all names of subdirectories from working directory:

. retrievefilenames, subdirectories

Retrieve filenames ending with ".txt" from working directory:

. retrievefilenames, searchexpression(\.txt$)

Shortcut:

. retrievefilenames, extension(txt)

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

. retrievefilenames, filedirectory(/home/user/Desktop) extension(txt) strip

Author

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

Saved results

retrievefilenames saves the following in r():

Locals

r(filenames) filenames retrieved

r(dirnames) subdirectory names retrieved (if used with option subdirectories)

Also see

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