help for xdir and xframedir (Roger Newson)

Create a resultsset with 1 observation per file or per frame

xdir [ ,
dirname(directory_name) pattern(file_pattern) ftype(file_type)

nofail respectcase

local(local_macro_name) plocal(local_macro_name)

list( [varlist] [if] [in] [ , [list_options] ] )

frame( framename [ , replace change ] )

saving(datafilename [, replace ])

norestore fast flist(global_macro_name)

path
idnum(#) idstr(string)
rename(oldvarname_1 newvarname_1 ... oldvarname_n newvarname_n)
gsort(gsort_list) keep(varlist)

]

xframedir [ ,
local(local_macro_name)

list( [varlist] [if] [in] [ , [list_options] ] )

frame( framename [ , replace change ] )

saving(datafilename [, replace ])

norestore fast flist(global_macro_name)

path
idnum(#) idstr(string)
rename(oldvarname_1 newvarname_1 ... oldvarname_n newvarname_n)
gsort(gsort_list) keep(varlist)

]

where directory_name is a directory name recognized by the operating environment currently being used,
file_pattern is a matching pattern recognized by the strmatch(s1,s2) function,
file_type is an item from the list

files dirs other

and list_options is a list of options accepted by the list command.

Description

xdir is an extended version of dir, or of the extended macro function dir.
It creates an output dataset (or resultsset),
with 1 observation for each file in a user-specified directory conforming to a user-specified pattern, and belonging to a user-specified file type,
and data on the file name and the directory name.
xframedir is an extended version of frames dir.
It creates a resultsset with 1 observation per frame in the memory.
The resultsset from xdir or xframedir may be listed using the list() option
and/or saved to a data frame using the frame() option
and/or saved to a file using the saving() option
and/or written to the memory using the norestore or fast option,
overwriting any existing dataset.
Alternatively (or additionally), a list of the file or frame names
may be saved in a local macro,
using the local() option, or the plocal() option for xdir.

Options

These options fall into the following 3 groups:

Option group Description

filespec_opts File-specifying options for xdir only

outdest_opts Output-destination options for the resultsset

conspec_opts Content-specifying options for the resultsset

File-specifying options for xdir only

dirname(directory_name) specifies a directory name under the current operating environment.
This directory name may be an absolute location (expressed as a full directory path)
or a relative location (expressed as a relative directory path).
If not specified, then the dirname() option defaults to the current directory location,
stored in the creturn result c(pwd) and output by the Stata pwd command.

pattern(file_pattern) specifies a file pattern, as recognized by the strmatch(s1,s2) function in Stata.
This file pattern is used to specify a list of names of files found in the directory
specified by the dirname() option.
If unspecified, then the pattern() option is set to pattern(*),
specifying all files, directories or other entries in the directory specified by dirname().

ftype(file_type) specifies a file type recognized by the extended macro function dir.
This file type may be files, dirs, or other,
specifying, respectively, files, directories, or entries that are neither files nor directories,
in the directory specified by the dirname() option.

nofail specifies that, if the directory contains too many filenames to fit into a macro,
then, instead of issuing an error, the filenames that fit into the macro should be returned.
nofail should rarely, if ever, be specified.

respectcase specifies that, under Microsoft Windows, xdir will respect the case of filenames when performing matches.
Unlike other operating systems, Microsoft Windows has, by default, case-insensitive filenames.
respectcase is ignored in operating systems other than Windows.

Output-destination options

local(local_macro_name) specifies the name of a local macro,
containing a list of the names of all the files (or other directory entries) for xdir,
or a list of all the frame names in the memory for xframedir)
The list will be in alphabetical (ascending ASCII or code-point) order.

plocal(local_macro_name) (xdir only)
specifies the name of a local macro,
in which a list of the complete path names (complete with the directory name)
of all the files (or other directory entries) will be stored.
The list will be in alphabetical (ascending ASCII or code-point) order.
The complete path name for a file is defined
as the directory name plus the directory separator plus the file name.
For instance, the file myfile.txt in the directory root
will have the complete pathname root/myfile.txt,
if the directory separator is /, as it is under Linux.
The plocal() macro is very useful for input to append
to concatenate multiple dataset files from a directory into the memory.

list(varlist [if exp] [in range] [, list_options ] )
specifies a list of variables in the output dataset,
which will be listed to the Stata log by xdir.
The user may optionally also specify if or in clauses to list subsets of observations
(corresponding to subsets of directory entries),
or change the display style using a list of list_options allowed as options by the list command.
If the rename() option is specified (see below),
then any variable names specified by the list() option must be the new names.
If the list() option is absent, then nothing is listed.

frame( name, [ replace change ] ) specifies an output data frame,
with one observation per directory entry,
and data on the attributes of the directory entry.
If replace is specified, then any existing data frame of the same name is overwritten.
If change is specified,
then the current data frame will be changed to the output data frame after the execution of xdir.
The frame() option may not specify the current data frame.
To do this, use one of the options norestore or fast.

saving(datafilename [, replace]) specifies an output file containing a Stata dataset,
with one observation per directory entry,
and data on the attributes of the directory entry.
If replace is specified, then any existing file of the same name is overwritten.

norestore and fast are two names for the same option.
They specify that the output dataset will be written to the current data frame in memory,
overwriting any pre-existing dataset.

Note that the user must specify at least one of the options local(), plocal(), list(),
frame(), saving(), norestore and fast.

flist(global_macro_name) specifies the name of a global macro,
containing a filename list (possibly empty).
If saving() is also specified,
then xdir will append the filename specified in the saving() option
to the value of the global macro specified in flist().
This enables the user to build a list of filenames in a global macro, containing the
output of a sequence of resultssets saved by xdir.
These files may later be concatenated using append.

Content-specifying options

path (xdir only) specifies that a new string variable path will be generated,
containing the complete path names for the files.
The complete path name for a file is defined
as the directory name plus the directory separator plus the file name.

idnum(#) specifies an ID number for the output dataset.
It is used to create a numeric variable idnum in the output dataset, with that value for all
observations.
This is useful if the output dataset is concatenated with other xdir or xframedir output datasets
using append.

idstr(#) specifies an ID string for the output dataset.
It is used to create a string variable idstr in the output dataset, with that value for all
observations. (An output dataset may have idnum, idstr, both or neither.)

rename(oldvarname_1 newvarname_1 ... oldvarname_n newvarname_n) specifies a list
of pairs of variable names. The first variable name of each pair specifies a variable in the output dataset,
which is renamed to the second variable name of the pair.
(See Output dataset created by xdir and xframedir below for details on output variables.)

gsort(gsort_list) specifies a generalized sorting order (as recognised by gsort)
for the observations in the output dataset.
If gsort() is not specified,
then the output dataset will be sorted by the variable list dirname filename.
If rename() is specified, then gsort() must use the new names.

keep(varlist) specifies a list of variables to be kept in the output dataset.
If keep() is not specified, then the output dataset contains all the variables listed in the next section.
If rename() is specified, then keep() must use the new names.

Output datasets created by xdir

and xframedir}

The output dataset (or resultsset) created by xdir
has one observation per entry, in the directory specified by the dirname() option,
of the type specified by the ftype() option,
and conforming to the file pattern specified by the pattern() option.
If the rename() option
is not specified, then it contains the following variables:

Default name Description

idnum Numeric dataset ID

idstr String dataset ID

dirname Directory name

filename File name

path File path

The otput dataset (or resultsset) created by xframedir
has one observation per data frame in the memory.
If the rename() option
is not specified, then it contains the following variables:

Default name Description

idnum Numeric dataset ID

idstr String dataset ID

framename Frame name

The variables idnum, idstr and path are only present if requested in the options of the same names.
The dataset is sorted by the variables dirname and filename (for xdir),
or by the variabl framename (for xframedir),
unless the gsort() option is specified..
All of these variables can be renamed using the rename() option,
or used by the gsort() option to specify the sorting order.
If the keep() option is used, then the output dataset will contain only the specified subset of these variables.

Remarks

xdir is an extended version of the dir command,
and uses the extended macro function dir
to produce a comparable list of directory entries under different operating environments.
Under specific operating environments, the user can use alternative packages for producing directory listings,
such as linuxlsd1 under Linux or Mac OS X,
or msdirb under Microsoft Windows.
These packages have syntax and output optimized for their specific operating environments.
The packages linuxlsd1 and msdirb can be downloaded from SSC.

Examples

. xdir, list(,)

. xdir, dir(.) list(,)

. xdir, dir(..) ftype(dir) list(,)

. xdir, saving(myxdir.dta, replace)

. xdir, norestore

. describe

. list

. xdir, norestore idstr("My directory listing")

. describe

. list

. xdir, fast

. describe

. list

. xdir, list(,) local(lalla)

. disp `"`lalla'"'

. xdir, path frame(mycontents, replace change)

. describe, full

. list, abbr(32)

. frame change default

. xframedir, list(, abbr(32))

Author

Roger Newson, Imperial College London, UK.
Email: r.newson@imperial.ac.uk

Also see

Manual: [D] dir, [P] Extended macro functions

On-line: help for dir, frames dir, Extended macro functions

help for linuxlsd1, msdirb if installed