WinFile (Class)

Version

Version 2.3.2 from 2012-10-05

Provides information about files and directories without using any .NET stuff.

Many methods (Dir+DirX for example) are MUCH faster than the .NET stuff.

The class contains shared methods only.

Almost all methods throw exceptions in case of an error.

Indexers

Note that there are fields available since version 1.7.0 useful to index the matrix returned by DirX . The field names start with "COL_" and "FA_" (for the file attributes). They assume a ⎕IO of 1. If you use ⎕IO←0 you have two options:

Use the

#.WinFile.((DirX'')[;COL_CreationDateName])

syntax or the

(#.WinFile.DirX '')[;COL_CreationDateName-~⎕IO]

syntax.

Kai Jaeger ⋄ APL Team Ltd

Homepage: http://aplwiki.com/WinFile

History

See: http://aplwiki.com/WinFile/ProjectPage

File creation date

Last access date

Last write date

Full name

8.3 name

Size in bytes

32 0x20 A file or directory that is an archive file or directory.

2048 0x800 A file or directory that is compressed.

64 0x40 This value is reserved for system use.

16 0x10 Flag that identifies a directory.

16384 0x4000 A file or directory that is encrypted.

2 0x2 The file or directory is hidden. It is not included in an ordinary directory listing.

128 0x80 A file that does not have other attributes set.

8192 0x2000 The file or directory is not to be indexed by the content indexing service.

4096 0x1000 The data of a file is not available immediately (offline storage).

1 0x1 A file that is read-only.

1024 0x400 A file or directory that has an associated reparse point, or a file that is a symbolic link.

512 0x200 A file that is a sparse file.

4 0x4 A file or directory that the operating system uses a part of, or uses exclusively.

256 0x100 A file that is being used for temporary storage.

65536 0x10000 This value is reserved for system use.

Report/change the current directory.

Returns a 1 if the path to be checked is fine, otheriwse 0.

If the path does not exist but the left argument is "CREATE!" it will be created.

Copy "Source" to "Target".

The left argument must be a file. Wildcard characters are not supported. The right argument might be a filename or a folder. If it is a folder the filename of "Source" is used for the new file.

CopyTo always overwrites the target file if there is any.

Examples:

'C:\readme.txt' #.WinFile.CopyTo 'D:\buffer\'

'C:\readme.txt' #.WinFile.CopyTo 'D:\buffer\newname.txt'

When the "Copy" operation fails a DOMAIN ERROR is thrown.

The (shy) result r is always an empty vector in order to make CopyTo callable from a direct function.

If you prefer exceptions over return codes see CopyTo

Copy "Source" to "Target".

The left argument must be a file. Wildcard characters are not supported. The right argument might be a filename or a folder. If it is a folder the filename of "Source" is used for the new file.

CopyTo always overwrites the target file if there is any.

Examples:

'C:\readme.txt' #.WinFile.CopyTo 'D:\buffer\'

'C:\readme.txt' #.WinFile.CopyTo 'D:\buffer\newname.txt'

When the "Copy" operation fails a DOMAIN ERROR is thrown.

The (shy) result r is always an empty vector in order to make CopyTo callable from a direct function.

If you prefer return codes over throwing an exception see CopyToWithRC

Delete one or more files.

Note that the explicit result tells you whether the file to be deleted existed upfront or not. It does not tell you whether the delete operation was successful or not. This is not a bug in WinFile , it is what the underlying Windows API function is returning. If you need to be sure that the file in question really got deleted use #.WinFile.DoesExistFile to find out.

Note that Delete does NOT support wildcards. If it finds wildcard chars it throws an error.

Returns a vector of character vectors each representing a fully qualified path which is a sub=path of "path". Empty if "path" does not contain any directories.

List the contents (names and attributes) of a given directory, by default the current one.

Pass "Recursive" as left argument to list all sub-directories, too.

By default, long names as well as short names together with file properties are returned but no timestamps. If you are in need for timestamps specify ('FileTime' 1) as left argument.

You can restrict the number of files returned by specifying ('NoOf' {anyNumber}).

Note that when a recursive scan is performed any wildcard chars in the right argument do effect the result list only but not the directories searched.

For example, this expression:

WinFile.DirX '*.svn'

returns a list with all files matching the pattern, even if they are contained in a sub-folder "abc" of the current dir which obviously doesn't match the pattern.

For addressing the file attributes see (and use) the FA_* and/or COL_* fields.

This example extracts the "Last write date" and the directory flag:

#.WinFile.((DirX '*')[;COL_LastWriteDate,FA_DIRECTORY])

List the contents (names only) of a given directory, by default the current one.

Pass "Recursive" as left argument to list all sub-directories, too.

Note that when "Recursive" is specified as left argument, any wildcard chars in the right argument do effect the result list only but not the the directories searched.

For example, this expression:

WinFile.Dir '*.svn'

returns a list with all directories matching the pattern, even if they are contained in a sub-folder "abc" of the current dir which obviously doesn't match the pattern.

Returns a Boolean for every dir in the right argument. The right argument can be one of:

• Simple string. Treated as name of a single directory.
• Vector of strings. Every item is treated as a directory name.

A 1 indicates that the corresponding directory exists.

Returns a Boolean for every file in the right argument. The right argument can be one of:

• Simple string. Treated as name of a single filename.
• Vector of strings. Every item is treated as a filename.

A 1 indicates that the corresponding file exists.

Returns a Boolean for every file or directory in the right argument. The right argument can be one of:

• Simple string. Treated as a single name (file or directory).
• Vector of strings. Every item is treated as a name (file or directory).

A 1 indicates that the corresponding file or directory exists.

If Y does not contain any "%" Y is passed untouched.

In case Y is empty R is empty as well.

Example:

'C:\Windows\MyDir' ←→ #.WinSys.ExpandEnv '%WinDir%\MyDir'

'C:\Windows\'  ←→ #.WinSys.ExpandEnv '%WinDir%\MyDir\..'

Expands "path" by replacing ".\" and "..\" with the real thing.

Return a vector of text vectors with the names of all drives, for example: "C:\"

Return a matrix with the names and the types of all drives.

The number of rows is defined by the number of drives found.

"Types" may be something like "Fixed", "CD-ROM", "Removable", "Remote"

Returns the name of an unused temporary filename. If "PathName" is empty, the default temp path is taken. This means you can overwrite this by specifying a path.

"PrefixString", if defined, is a leading string of the filename going to be generated. This is not the same as

'pref',GetTempFileName ''

because specified as left argument it is taken into account when the uniquness of the created filename is tested.

Returns the name of the path to the Windows temp directory on your system.

Returns 1 if empty, 0 if not and ¯1 if the directory could not be found or is a file.

The right argument can be one of:

• Simple string. Treated as a single name (file or directory).
• Vector of strings. Every item is treated as a name (file or directory).

Returns a 1 in case "filename" is okay. "filename" must not have a path.

In order to check this a file with the given name is created in the temp folder.

Returns a 1 in case "filename" is okay. "foldername" must not have a path.

In order to check this a directory "foldername" is created in the temp folder.

Checks whether "filename" is valid in terms of the Win32 sub-system.

Note that POSIX and NTFS rules are different!!

Note also that this function does not check for ":/\" which strictly speaking are not allowed in a filename but in a path.

If you want perform strict checking then specify "NoPath" as right argument. The left argument defaults to '', meaning that "filename" is considered to be a full path; that includes /\ as well as :.

Returns a list with all directories in "Path". In order to get also sub-directories specify "recursive" as left argument.

Wildcards are supported. Note that when used with "Recursive" as left argument the wildcards only affect the resulting list of directories but NOT the directories searched.

Examples:

ListDirsOnly '?.svn'          ⍝ Is there a dir ".svn" in the current dir? 
ListDirsOnly '*.acre'         ⍝ List all dirs ending with ".acre" in current dir 
ListDirsOnly 'ThisFolder'     ⍝ Assums "ThisFolder" is a dir & looks into it 
ListDirsOnly 'ThisFolder\'    ⍝ Same as before 

This function returns a matrix with all indices useful to index the result of DirX .

Note that these are the fields starting their names with COL_ .

Example to get the last write date:

(#.WinFile.DirX '*')[;#.WinFile.FA_HIDDEN]

The columns returned:

[;1] Name

[;2] Value (decimal)

[;3] Value (hex)

[;4] Remark

See also ListFileAttributes .

Returns a matrix with all fields starting their names with FA_ .

These are used to index the result of DirX in order to get a particular file attribute. For example. in order to find out whether a file is hidden or not:

(#.WinFile.DirX '*')[;#.WinFile.FA_HIDDEN]

These columns are returned:

[;1] Name

[;2] Value (decimal)

[;3] Value (hex)

[;4] Remark

See also ListDirXIndices .

Create (make) a new directory.

Result is always an empty vector.

Moves "Source" to "Target".

The function returns a return code and a textual message which is empty in case of success.

If you prefer an exception over a return code see MoveTo .

The left argument must be a file. Wilcard characters are not supported. The right argument might be a filename or a folder. If it is a folder the filename of "Source" is used for the new file.

MoveTo always overwrites the target file if there is any.

Examples:

'C:\readme.txt' #.WinFile.MoveTo 'D:\buffer\' 
'C:\readme.txt' #.WinFile.MoveTo 'D:\buffer\newname.txt' 

Moves "Source" to "Target".

In case of an error an exception is thrown. If you prefer a return code returned as explicit result see MoveToWithRC .

The explicit result is always an empty text vector.

The left argument must be a file. Wilcard characters are not supported. The right argument might be a filename or a folder. If it is a folder the filename of "Source" is used for the new file.

MoveTo always overwrites the target file if there is any.

Examples:

'C:\readme.txt' #.WinFile.MoveTo 'D:\buffer\' 
'C:\readme.txt' #.WinFile.MoveTo 'D:\buffer\newname.txt' 

If ⎕WSID is relative (no "/" or "\" char in the path) the function does nothing.

Otherwise the current directory is changed to that it becomse the path part of ⎕WSID

Print Working Directory. Shortcut for Cd'' .

Read contents as chars. File is tied in shared mode.

Removes an empty directory. If the left argument is "Recursive" then any files and sub-directories are deleted as well.

Since this operation might fail simply because another user is just looking into one of the directories going to be deleted, a boolean value is returned indicating success (0) or failure (positive error indicating the problem). As a second result "more" is returned.

Note that error 145 is returned on an attempt to delete a non-empty directory without specifying "Recursive" as left argument.

Data must be a string or a vector of strings. If file already exists it is replaced.

Compare the "last changed at" timestamp of both, Filename1 and Filename2 .