{smcl}
{* revised 13nov2013}{...}
{cmd:help filelist}
{hline}

{title:Title}

{phang}
{bf:filelist} {hline 2} Recursively search directories for files


{title:Syntax}

{p 4 16 2}
{cmd:filelist} 
	{cmd:,}
	[{opt d:irectory(dirpath)} 
	{opt p:attern(search_pattern)} 
	{opt s:ave(stata_dataset)} 
	{opt replace}
	{opt l:ist} 
	{opt nor:ecursive}]
	

{title:Description}

{pstd}
{cmd:filelist} searches {it:dirpath} for files that match
{it:search_pattern} and continues searching recursively in all
its subdirectories. If {opt d:irectory(dirpath)} is omitted,
the search starts from the current directory 
(see {help pwd} and {help cd}). 

{pstd}
The dataset in memory is preserved if {opt s:ave(stata_dataset)}
is specified. Otherwise, the dataset in memory is replaced with the
search results. The {cmd:dirname} variable stores the 
file path and the {cmd:filename} variable stores the file name.

{pstd}
By default, {cmd:filelist} will pick up all files, including
system files that are usually hidden. To target a specific
type of file using a pattern in the file name, use the 
{opt p:attern(search_pattern)} option.
The {it:search_pattern} string must conform to the rules of the {help strmatch()}
function. For example, with {opt pattern("*.csv")}, {cmd:filelist} will return only
file names that end with ".csv".


{title:Options} 

{phang}{opt d:irectory(dirpath)} indicates the directory
	where the search is to take place. If omitted, the search will
	start from the current directory.
	
{phang}{opt p:attern(search_pattern)} is used to identify files using
	a pattern in their name. The {it:search_pattern} must conform to 
	the rules of the {help strmatch()} function. 
	
{phang}{opt s:ave(stata_dataset)} is used to save results
	to disk. The {it:stata_dataset} is stored in the current 
	directory.

{phang}{opt replace} is used to overwrite an existing {it:stata_dataset}.
	
{phang}{opt l:ist} is used to list search results in the Results window.

{phang}{opt nor:ecursive} is used to restrict the search to {it:dirpath},
excluding its subdirectories. 


{title:Examples}

{pstd}
To find all files in the current directory and its subdirectories

        {cmd:.} {stata filelist}

{pstd}
If there is a "main" directory within the current directory, you can
search for all Stata datasets in "main" using

        {cmd:.} {stata filelist, dir("main") pat("*.dta")}
        
{pstd}
To search for all comma-separated data files in the "main" directory 
within the current directory and save the results to disk
        
        {cmd:.} {stata filelist, dir("main") pat("*.csv") save("csv_datasets.dta")}
        
{pstd}
You can run the following code if you want to use the saved search 
results to append all csv data files

        {cmd:} use "csv_datasets.dta", clear
        {cmd:} local obs = _N
        {cmd:} forvalues i=1/`obs' {
        {cmd:}   use "csv_datasets.dta" in `i', clear
        {cmd:}   local f = dirname + "/" + filename
        {cmd:}   insheet using "`f'", clear
        {cmd:}   tempfile save`i'
        {cmd:}   save "`save`i''"
        {cmd:} }

        {cmd:} use "`save1'", clear
        {cmd:} forvalues i=2/`obs' {
        {cmd:}   append using "`save`i''"
        {cmd:} }


{title:Author}

{pstd}Robert Picard{p_end}
{pstd}picard@netbox.com{p_end}


{title:Acknowledgments}

{pstd}A question on Statalist from Tim Evans was the stimulus for
writing this program.