
 -----------------------------------<win_dir>-----------------------------------

 Syntax:      include win_dir.ew
              x = win_dir(st)

 Description: Return directory information for the file or directory named by
              st. If there is no file or directory with this name then -1 is
              returned. st may contain * and ? wildcards to select multiple files.

              This information is similar to what you would get from the DOS
              DIR command. A sequence is returned where each element is a
              sequence that describes one file or subdirectory.

              If st names a directory you may have entries for "." and "..",
              just as with the DOS DIR command. If st names a file then x will
              have just one entry, i.e. length(x) will be 1. If st contains
              wildcards you may have multiple entries.

              Each entry contains the name, attributes and file size as well as
              the year, month, day, hour, minute and second of the last
              modification. You can refer to the elements of an entry with the
              following constants defined in file.e:

                  global constant D_NAME = 1,
                            D_ATTRIBUTES = 2,
                                  D_SIZE = 3,
              
                                  D_YEAR = 4,
                                 D_MONTH = 5,
                                   D_DAY = 6,
              
                                  D_HOUR = 7,
                                D_MINUTE = 8,
                                D_SECOND = 9
              
              The attributes element is a string sequence containing characters
              chosen from:

                  'd' -- directory
                  'r' -- read only file
                  'h' -- hidden file
                  's' -- system file
                  'v' -- volume-id entry
                  'a' -- archive file
              
              A normal file without special attributes would just have an empty
              string, "", in this field.

 Comments:    The top level directory, e.g. c:\ does not have "." or ".."
              entries.

              This function is often used just to test if a file or directory
              exists.

              Under WIN32, st can have a long file or directory name anywhere
              in the path.

              If the specified path is a diretory without a trailing backslash,
              (i.e. "C:\WINDOWS") the entry for that directory is returned. To
              get the files in the directory, include a trailing backslash in
              the path (i.e. "C:\WINDOWS\").

 Warning:     This function uses Unicode by default. Unicode is only supported
              in Windows NT/2000/XP. For Win9x systems, set USE_UNICODE to 0.

 Example:

              d = win_dir(current_dir())
              
              -- d might have:
                {
                  {".",    "d",     0  1994, 1, 18,  9, 30, 02},
                  {"..",   "d",     0  1994, 1, 18,  9, 20, 14},
                  {"fred", "ra", 2350, 1994, 1, 22, 17, 22, 40},
                  {"sub",  "d" ,    0, 1993, 9, 20,  8, 50, 12}
                }
              
              d[3][D_NAME] would be "fred"
              
               
 Example Program: win_dir_demo.exw

 See Also:    walk_win_dir


 --------------------------------<walk_win_dir>---------------------------------

 Syntax:      include win_dir.e
              i1 = walk_win_dir(st, i2, i3)

 Description: This routine will "walk" through a directory with path name given
              by st. i2 is the routine id of a routine that you supply.
              walk_dir() will call your routine once for each file and
              subdirectory in st. If i3 is non-zero (TRUE), then the
              subdirectories in st will be walked through recursively.

              The routine that you supply should accept the path name and dir()
              entry for each file and subdirectory. It should return 0 to keep
              going, or non-zero to stop walk_dir().

 Comments:    This mechanism allows you to write a simple function that handles
              one file at a time, while walk_dir() handles the process of
              walking through all the files and subdirectories.

              Using walk_win_dir() is *much* faster than using walk_dir() since
              files are not collected in memory ahead of time. This way, you can
              walk through directories containing thousands of files without
              seeing a drop in speed.

              Another advantage of walk_win_dir() over walk_dir() is that you
              may include wildcards (* or ?) in your path, so only specific
              files are visited.

 Warning:     This function uses Unicode by default. Unicode is only supported
              in Windows NT/2000/XP. For Win9x systems, set USE_UNICODE to 0.

 Example:

              function look_at(sequence path_name, sequence entry)
              -- this function accepts two sequences as arguments
                  printf(1, "%s\\%s: %d\n",
                         {path_name, entry[D_NAME], entry[D_SIZE]})
                  return 0 -- keep going
              end function
              
              exit_code = walk_win_dir("C:\\MYFILES", routine_id("look_at"), TRUE)
              
               
 See Also:    win_dir


