FILES

lists files in the specified auxiliaries using a MORE filter and columns

<name> Full or partial file name of interest
<ext>  Filename extension of interest (defaults to TMP|PRM|TXT)
<aux>  Auxiliary of interest (or path in quotes)
<uid>  User ID for the area of interest (not implemented)

FILES uses operating system library calls to retrieve a list of wildcarded
files following the Midas auxiliary structure.  The output is pushed through
the MORE filter and is listed in columns to show more files in one screen.

Both <name> and <ext> can contain multiple expressions to match separated
by the | character.  For example:

  FILES a*|b*|c* txt|key

would list all files beginning with a, b, or c having the extension .txt or
.key, the extension can also contain wildcards (i.e. txt|k* would match .txt
or any extension beginning with k..

A full path name can be given in the <name> argument and the auxiliaries
will be bypassed completely.  However, if a path name is given, you are
limited to specifying only one <name> expression to match (i.e. you
cannot use the '|' for the file name pattern match.)

The path can also be entered in the <aux> field to bypass the aux table.
The path string must end in a path delimiter and be entered in quotes.

The /F switch specifies a Midas file to receive the output of the command.
/F=FILENAME will use FILENAME.TMP; /F alone uses FILES.TMP . This file can be
used with the FORALL command to ERASE, SAVE or CONVERT, etc. a group of files.
If the /F switch is present, one can not use the /E switch to erase.

Since NeXtMidas 2.7.2: The /LIST= switch specifies a result name to receive the
output of the command as a comma-separated string list of file names/paths.

Since NeXtMidas 2.9.0, it is possible to specify multiple extensions in the
NAME=. Furthermore, if using the /STRICT switch, these extensions will only
apply to the name given with them. For example:

  nM> files/strict name=S*.jpg|*v2.prm  aux=dat

will list ONLY those files in the DAT aux that are .jpg files that start with
's' or .prm files that end with 'v2'. The default behaviour when not using
/STRICT is to combine the filters, so in the above example any file that
started with an 'S' or ended with 'v2' that was EITHER a jpg or prm would get
returned.  Note that defining extensions using EXT= will override the new
behaviour.

Since NeXtMidas 3.1.0, it is possible to exclude certain AUXs from being
searched when the files command is used to find files that match a given
filter. This can be done in two ways: using the system environment variable
NM_COMPLETION_AUX_EXCLUDE=<auxlist> or the switch /EXCLUDE=<auxlist>. In
each case, <auxlist> is a list of pipe ('|') separated AUXs to be skipped.
Note: if NM_COMPLETION_AUX_EXCLUDE is set AND the /EXCLUDE switch is used,
the /EXCLUDE switch will override.

NOTE:
  If multiple AUX's point to the same disk location (e.g. AUX[1] and AUX[CWD]
  are the same) then FILES will only list one of them.

NOTE:
  Directories can be listed by using the special extension "dir".
  When specifying a directory, it must end with a path delimiter.
  A non-AUX path can be entered directly in the <AUX> parameter slot in quotes.

Examples:
  1. To list the headers of all files beginning with "tes"
      nM> files/h tes*

  2. To erase all files with "temp" in the filename
      nM> files/f *temp*
      nM> forall files erase #
    or
      nM> files/e *temp*

  3. List all the files in AUX=1 and show their sizes
      nM> files/h AUX=1

  4. List all of the files starting with world and having a .shp extension
      nM> files world*.shp

  5. List each TXT file in a directory and then do something with it

      files/list=files/nameonly "^{mydir}" ext=txt
      foreach name inlist files
        say "Found TXT file ^name in ^mydir"
      endfor
  6. List all the files in AUX=DAT that are .jpg files starting with an 's' or
     .prm files that end with 'v2'
       nM> files/strict name=S*.jpg|*v2.prm  aux=dat

  7. List only the directories (no files) under the current working directory
      nM> files ext="dir" aux=aux.cwd

  8. List only the directories (no files) under the /midas/data1/ directory
      nM> files ext="dir" aux=/midas/data1/

  9. List all of the files starting with world and having a .shp extension,
     but skip (exclude) any files in the current working directory
      nM> files/exclude=cwd world*.shp

Switches:
  /E            - Erase the files specified. Can not be used with /F switch.
  /EXCLUDE=<AUX>- List of pipe ('|') separated AUXs to be excluded when looking
                  for files that match a filter (since 3.1.0).
                  Note: This will override any AUXs listed in the environment
                  setting NM_COMPLETION_AUX_EXCLUDE.
  /F=<filename> - Specifies a filename to receive output, if blank outputs
                  to FILES.TMP
                  If the filename has a .txt extension, then the output file
                  will be a text file with items (entries) separated by a
                  newline (LF char) versus a BLUE file (since 3.1.1).
  /FORM=<form>  - Format of type 1000 file specified by /F=. [DEF=XA]
  /H            - Creates a column-based table with file type, data format,
                  and number of elements for each file (this is similar to
                  "ls -l" in Unix).
  /LIST=<res>   - Outputs the file listing to the named result. The format will
                  be a comma-separated string including each item found. If
                  nothing is found, an empty string will be output (since 2.7.2)
  /NAMEONLY     - When used with /F= or /LIST= causes only the name of the file
                  to be output rather than the full file path. [DFE=FALSE]
                  (Since NeXtMidas 2.7.2)
  /R=           - Recursive directory list when <aux> is a path. [DEF=NONE]
                  The modes are:
                    NONE - No recursion
                    FULL - To end of each directory path
                    LEVELFIND - To the level of found file, no deeper
                    FIRSTFIND - To the first found file, then return
  /STRICT       - In conjunction with NAME=[], use extension listed with the
                  particular filename only (ignores EXT=[]) (since 2.9.0).
  /V            - Successively lists the headers of each DataFile (other files
                  will be skipped over). This switch overrides and disables /H.

SEE ALSO:  FORALL, FOREACH