dir
| Definition: | object res = dir(string path, integer date_type=D_MODIFICATION) |
| Description: |
path: the name of the file or directory to query date_type: one of D_CREATION(1), D_LASTACCESS(2), D_MODIFICATION(3), or NULL(0). Omitting this parameter preserves legacy behaviour. Return directory information for the named file or directory, which can be absolute or relative to the current directory. If there is no file or directory with this name then -1 is returned. On Windows path can contain * and ? wildcards to select multiple files. |
| pwa/p2js: | Not supported. |
| Comments: |
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 path names a directory you may have entries for "." and "..", just as with the DOS DIR command. If path names a file then res will have just one entry, i.e. length(res) will be 1. If path 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 creation, last access, or last modification. Should you need further clarification (specifically the precise conditions under which last access changes, which may for performance reasons be set to, say, max once per day, or never) please refer to your operating/file system documentation. You can refer to the elements of an entry with the following constants (automatically defined in psym.e/syminit):
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 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. The top level directory, e.g. C:\ does not have "." or ".." entries. Legacy code often uses this function just to test if a file or directory exists, though the newer file_exists() is usually faster. Under Windows, path can have a long file or directory name anywhere in the path. Under Linux, the only attribute currently available is 'd'. On Windows, the file name returned in D_NAME will be a long file name. A date_type of NULL is intended for use by file_exists(), and causes this routine to not bother actually reading directory contents, or retrieving any file details, so it will always return either -1 or {}. |
| Example: |
d = dir(current_dir())
-- d might have:
{
{".", "d", 0 2012, 1, 18, 9, 30, 02},
{"..", "d", 0 2012, 1, 18, 9, 20, 14},
{"fred", "ra", 2350, 2012, 1, 22, 17, 22, 40},
{"sub", "d" , 0, 2013, 9, 20, 8, 50, 12}
}
d[3][D_NAME] would be "fred"
d[i][D_YEAR..D_SECOND(or $)] are all valid timedates
|
| Example Programs: |
demo\dirc.exw - a quick and dirty directory compare that I wrote to get a release out, which may or may not ever get used again.
demo\pGUI\pdemo\demo.ew - part of Phix\pdemo.exw which finds/lists all demos in the Phix/demo directory, see the dload() routine. |
| Implementation: | See builtins\pdir.e (an autoinclude) for details of the actual implementation. |
| See Also: | wildcard_file, current_dir, open, file_size_k, timedate |