Dir Xcfn

SuperCard: the easiest, most flexible way to make stuff for your Mac

	The Extended Documentation project is designed to explain some of the more complex tools and features in SuperCard's armoury. Thanks to the patience and skill of the authors, some of the more powerful features of SuperCard have been revealed.

AUTHOR

Mark Lucas

USAGE

Dir( folderPath [ ,showInvFlag [ ,descendFlag [ ,delimiter(s) [ ,returnType [ ,typeOrCreator]]]]])

put Dir("My HD:MyFolder:") into dirList

put Dir("My HD:MyFolder:",true,true,tab&cr,"folders") into folderList

put Dir("My HD:MyFolder:",false,true,tab&cr,"type","TEXT") into textFileList

DESCRIPTION

The Dir external function (XFCN) is used to get the directory listing from any folder path, and to provide a variety of additional information on the files and folders in the listing.

COMMENTS

The Dir XFCN takes 6 parameters. All but the first are optional. These parameters are:

Parameter Description

folderPath This parameter contains the full path to the disk or folder from which the contents will be listed. You may include the trailing colon character (which is ordinarily part of a folder path) or not; Dir will automatically add one if you don't provide one.

showInvFlag (optional) This parameter defines whether Dir should return invisible files/folders in the returned list.

If this parameter is set to true, the returned list will contain files and/or folders which are invisible in the Finder (such as Desktop files or custom icons).

If this parameter is set to false, invisible files/folders will not be returned in the list.

The default for this parameter is false if it is not passed, or if empty or blank ("") is passed.

descendFlag (optional) This parameter defines whether Dir should get the contents of sub-folders of folderPath.

If this parameter is set to true, Dir will recursively descend into sub folders and return the full pathnames to their contents as well as the contents of the folder supplied in folderPath. Dir will also return complete pathways for any files or folders found, instead of just the names of the files/folders.

If this parameter is set to false, only the contents of folderPath will be returned.

The default for this parameter is false if it is not passed, or if empty or blank ("") is passed.

delimiter(s) (optional) This controls whether Dir returns other information besides item names, and what characters are used to separate items in the returned list.

If this parameter is omitted or empty, it defaults to a carriage return.

If it contains (or defaults to) a single character, Dir will return just the names of the items in folderPath, separated by that character.

If it contains two characters, Dir will also return a variety of information about each item in folderPath. The first character will be used to separate the 'lines' of the returned list, and the second character to separate the items on each line. Each line of this long form of the returned list is called an infoRecord.

The infoRecord for a file contains 14 items:

1. name of the file (if descendFlag is false) or the full path to the file (if descendFlag is true)

2. creation date (in seconds)

3. modification date (in seconds)

4. backup date (in seconds)

5. visible flag ("T" if file is visible, "F" if file is invisible)

6. Finder label color (0-7, where 0 is "None" and 1 is the color at the bottom of the Label menu (usually "Project 2") and 7 is the color at the top of the Label menu (usually "Essential"))

7. FCMT Rez ID

8. alias flag ("T" if file is an alias, "F" if file is not an alias)

9. file type code

10. file creator code

11. logical data fork length*

12. physical data fork length*

13. logical resource fork length*

14. physical resource fork length*

* Note that a file's size as shown in the Finder is the physical length, whereas the actual length of its contents is the logical length. For an explanation of the differences between physical and logical file sizes, see Special Considerations, below.

The infoRecord for a folder contains 8 items:

1. name of the folder (if descendFlag is false) or the full path to the folder (if descendFlag is true)

2. creation date (in seconds)

3. modification date (in seconds)

4. backup date (in seconds)

5. visible flag ("T" if file is visible, "F" if file is invisible)

6. Finder label color (0-7, where 0 is "None" and 1 is the color at the bottom of the Label menu (usually "Project 2") and 7 is the color at the top of the Label menu (usually "Essential"))

7. FCMT Rez ID

8. the number of files/folders within the folder

returnType (optional) This parameter determines what kind of information will be returned (files, folders, specific file types, etc.). Note that this may or may not include invisible files/folders, depending on the value of showInvFlag.

The parameter can contain one of the following five strings:

"All" - Returns both files and folders contained in folderPath.

"Files" - Returns only files contained in folderPath.

"Folders" - Returns only folders contained in folderPath.

"Type" - Returns only files whose Type code matches the 4-character string passed in the typeOrCreator parameter (see below).

"Creator" - Returns only files whose Creator code matches the 4-character string passed in the typeOrCreator parameter (see below).

The default for this parameter is "All" if it is not passed, or if empty or blank ("") is passed.

typeOrCreator (optional) If the string passed for returnType is "Type" or "Creator", this parameter contains the four-character Type or Creator code, whichever is appropriate.

This parameter is ignored if returnType is not "Type" or "Creator".

Note that the four-character code must be exactly four characters, and is case sensitive.

The following example shows how to use Dir to create a menu based on the contents of a folder. In this instance, the folder is called Extras and is located in the same folder as the main project, and calls a central DoExtra handler to execute the Extra:

on MakeExtrasMenu
set lockMenus to true

-- Delete the 'old' Extras menu before making a new one
if exists(menu "Extras") then delete menu "Extras"
put Dir(projPath(this proj) & "Extras:") into extraList

-- Make new Extras menu
new menu "Extras"
set the script of menu "Extras" to "on itemSelect" & cr & ¬
"DoExtra (short name of the target)" & cr & "end itemSelect"

repeat with x = 1 to the number of lines of extraList
if x = 1 then
insert item after menu "Extras"
else
insert item after last item of menu "Extras"
end if
set the name of item x of menu "Extras" to ¬
(line x of extraList)
end repeat

insert menu "Extras"
set lockMenus to false
end MakeExtrasMenu

The example above does not discriminate between files or folders when building the menu, and accepts all file types. The following example is the same as the above, but restricts the items in the menu to only files of type MDO3 (SuperCard 3.x documents):

The following example takes the recursively descending contents of a folder and displays the entire file/folder hierarchy in a list, with the Type and Creator codes displayed after each file in the list. This can be done because Dir returns the full paths to all files and folders in folderPath when the descendFlag is true. And due to the order that Dir uses (see Special Considerations, below), we can use this to our advantage. Also, note the method of checking the number of items returned in the infoRecord to determine if it is a file or folder being referenced.

function GetHierarchy folderPath

-- Set up local variables
put "" into tHierarchy
put " " into spcHolder
set the itemDel to colon
set the wordDel to tab
put the number of items of folderPath into tRootLevels

-- Get the list from Dir
put Dir(folderPath, false, true, return&tab, "all") into tList
repeat with x = 1 to the number of lines of tList
put line x of tList into tListLine

-- Extract path, name, type & creator codes from infoRecord
put ((the num of words of tListLine) = 8) into isFolder
put word 1 of tListLine into tPath
put last item of tPath into tName
if isFolder then put "" into TC
else
put "(" & (word 9 of tListLine) & "/" & ¬
(word 10 of tListLine) & ")" into TC
end if

-- Assemble extracted data
delete item 1 to tRootLevels of tPath
put (the number of items of tPath) - 1 into tLevel
if tLevel <> 0 then
put char 1 to (2*tLevel) of spcHolder into spcPad
else
put "" into spcPad
end if
put spcPad & tName & " " & TC into line x of tHierarchy
end repeat

set the itemDel to comma
set the wordDel to space
return tHierarchy
end GetHierarchy

RETURNED VALUE

As an external function, Dir will return the file or folder list if it executes successfully. If there is an error, the first line of the data that is returned will be false, and the second line will contain the error condition.

SPECIAL CONSIDERATIONS

Dir automatically filters out the carriage return at the end of the 'Icon\r' files which are used by the Finder for custom icons, but be aware that some file names may still contain unexpected chars. Fortunately most such oddball files are also invisible. You should put a sanity check in your scripts (which counts the number of items per line) when using the multi-item (i.e., two-delimiter) format.

The only completely safe delimiter is colon (:) (since it can't be used in filenames), but can be difficult to parse when using the multi-item (i.e. two-delimiter) format. It is suggested that you use tab as the item delimiter and return as the line delimiter in these cases.

When recursively descending through files and folders, Dir will retrieve the files and folders in alphabetical order (as would be displayed in the Finder), and will follow each folder that it encounters to its full depth before returning. To better understand this, you can switch to the Finder and open a folder that contains other folders. Set the view to By Name, and toggle open all the folder triangles until the hierarchy is completely expanded. This list (in the order displayed) would be what Dir returns. A sample of this is displayed below:

* List returned by Dir:

My HD:Adobe Acrobat:Acrobat™ Reader 3.0
My HD:Adobe Acrobat:Fonts
My HD:Adobe Acrobat:Help
My HD:Adobe Acrobat:Help:Help-Reader.pdf
My HD:Adobe Acrobat:Optional Plug-Ins
My HD:Adobe Acrobat:Optional Plug-Ins:ReadMe-Optional.pdf
My HD:Adobe Acrobat:Plug-Ins
My HD:Adobe Acrobat:Plug-Ins:Acrobat™ Weblink
My HD:Adobe Acrobat:Plug-Ins:ReadMe-PlugIns.pdf
My HD:Adobe Acrobat:ReadMe-Reader3.0

Physical vs. Logical File Sizes

To understand the difference between physical and logical file sizes, one needs to understand how files are stored on the Macintosh.

Each volume contains a certain number of spaces (called blocks) that are used to store files. The size of each block (the block size) is determined by the MacOS HFS file system, which places a maximum limit on the number of blocks that a volume may contain. The larger the capacity of the volume, the larger the block size; for example, a 2GB hard disk uses 19K blocks, whereas a 250MB hard disk uses 5K blocks.

Only whole blocks may be allocated when storing files, so that a file may take up one or more whole blocks on the disk. If you had a 2GB disk and created a blank document in SimpleText, when you saved it, the file would take up one complete block. If you were to Get Info on the file in the Finder, you would see that the dialog would display this information:

Size: 19K on disk (332 bytes used)

This means that the file is occupying one 19K block, but only 332 bytes of data are contained in the file. The physical size of this file is 19K; the logical size of this file is 332 bytes.

If you had a file stored on this 2GB volume whose logical size was 20,100 bytes, its physical size would be 38K (two 19K blocks), since only whole blocks may be allocated when storing files. However, the same file stored on a 250MB volume would only take 25K (five 5K blocks). As you can see, the bigger the volume, the more of its overall capacity goes to waste.

ERROR CONDITIONS

If you pass a path for folderPath that does not exist, the second line of the result function will contain the string No such folder.

If you pass a value for returnType that is not one of the strings supplied above, the second line of the result function will contain the string Invalid command -> (the name of the invalid command).