{smcl}
{* 15dec2010}{...}
{hi:help collectpaths}
{hline}

{title:Title} 
 
{cmd:collectpaths} {hline 2} Return file paths in local macros

{title:Syntax}

{pmore}{cmdab:collectpaths} {it:epath} [{cmd:;} {it:epath} {cmd:...}]
[{cmd:,} {opt fn(string)} {opt fpaths(string)} {opt fnames(string)} {opt fexts(string)} {opt os}]

{pstd}Where {it:epath} is as documented in {help collect}.

{title:Description}

{pstd}{cmd:collectpaths} finds files whose paths match the criteria in the {it:epath}s, and returns all of their bits, and the number found, in local macros.

{pstd}The info for each file is returned in three bits: the path to the file, the file name, and the file extension. The options can be used to specify the names of the relevant macros.
If no macro name is specified for a particular bit, the option name itself will be used.

{pstd}Examples:

{pstd}{cmd:collectpaths c:/top/next/onefile.dta}

{pmore}would return {cmd:c:/top/next/} in macro {cmd:fpaths1}, {cmd:onefile} in {cmd:fnames1}, and {cmd:.dta} in {cmd:fexts1} (and {cmd:1} in {cmd:fn})

{pstd}{cmd:collectpaths c:/top/next/onefile.dta, fpaths(mydir) fnames(myfile) fexts(myext) fn(count)}

{pmore}would return {cmd:c:/top/next/} in macro {cmd:mydir1}, {cmd:onefile} in {cmd:myfile1}, and {cmd:.dta} in {cmd:myext1} (and {cmd:1} in {cmd:fn})

{pstd}When multiple files are found, each is returned in the three relevant macros, with the corresponding suffixes: {cmd:2}, {cmd:3}, etc.

{title:Options}

{phang}{opt os} causes paths to be returned using the directory separator of the host operating system (ie, {cmd:\} for windows, {cmd::} for mac, {cmd:/} for linux). Otherwise, stata's general purpose {cmd:/} is used.

{pmore}Note that if backslashes are returned, the construction {cmd:`fpaths1'`fnames1'} will not work, because the backslash at the end of {cmd:fpaths1} will prevent the following macro from expanding.
When using backslashes, insert an extra backslash between paths and names: {cmd:`fpaths1'\`fnames1'}.

{title:Examples}

{pstd}{cmd}collectpaths some filenames*

{pstd}forval f=1/`fn' {{p_end}
{pmore}usel `fpaths`f''`fnames`f''`fexts`f''{break}
drop somevars{break}
savel newprefix-`fnames`f''{break}
}{p_end}{txt}

{title:Also see}

{pstd}Online: {help collect}

{pstd}Contact: {browse "mailto:elliott.lowy@va.gov":Elliott Lowy}