filecatalog(
filecatalog(
ROOTPATH
,
PATTERN
,
OPTION
,
VALUE
)

The filecatalog( function builds a text array listing the files in a folder, including any subfolders of that folder.

Parameters

This function has four parameters:

rootpath – path of the folder to be cataloged. This may be in either UNIX or HFS format.

pattern – wildcard pattern which may contain `*` and `?` for matching file and folder names. This parameter is optional. Note: If this parameter starts with a period, it is treated as a list of file extensions.

option – this and the following parameter are optional, and may also be repeated. It specifies an option for modifying the operation of the filecatalog( function. See the text below for details.

value – value of the option.

Description

This function builds a text array listing the files in a folder, including any subfolders of that folder. If only one parameter is supplied, the function will list every file inside the specified folder. This example will return a list of every file inside your Dropbox folder:

    filecatalog("~/Dropbox")

You can add a second parameter to list only files that match a wildcard pattern. This example lists only files that contain the word baby (the word baby may be in either the filename or in the name of any folder enclosing the file).

    filecatalog("~/Dropbox","*baby*")

If the pattern starts with a period, it specifies a list of file extensions that will match (when doing this you cannot use the `*` and `?` wildcard characters). This example lists all of the image files in your Dropbox folder.

    filecatalog("~/Dropbox",".jpg.png.gif")

#### Option/Value Pairs

You can add one or more option/value pairs to the function to modify how the list of files is collected. These option/value pairs can be used with or witout a pattern as the second parameter (you can also specify patterns using an option/value pair, as described below).

    filecatalog(root,option,value,option,value ... option,value)
    filecatalog(root,pattern,option,value,option,value ... option,value)

The avilable options are: wildcard, extensions, typecreator, hfs, hidden and insidepackages. Each of these options are described in detail below.

#### Wildcard

This option sets up a wildcard pattern using the `*` and `?` wildcard characters. This example lists files that are related to holidays (or at least contain holidays in the file or folder name).

    filecatalog("~/Dropbox","wildcard","*holiday*")

#### Extensions

This option allows you to specify a list of file extensions to include in the list. This example will include several different types of image files:

    filecatalog("~/Dropbox","extensions",".jpg.jpeg.png.gif.tif.tiff")

Note: you can combine wildcard and extension options, for example to list baby pictures.

#### IncludeFolders

Normally the filecatalog( function doesn’t list folders, only files. However, by using the IncludeFolders option you can specify that folders should be included in the output list as well.

    filecatalog("~/Dropbox","includefolders","true")

#### ExcludeFiles

If you want to list only folders, use the excludefiles option.

    filecatalog("/Applications","excludefiles","yes")

This formula will list the folders inside the Applications folder, but not the applications themselves or other files within the Applications folder.

    /Applications/Utilities
    /Applications/3rd Party Applications
    /Applications/Setapp

Note: When you enable the ExcludeFiles option, Panorama automatically enables the IncludeFolders option (see above).

#### Type/Creator Codes

This option allows you to specify what types of files to list by using the old “Mac OS” type/creator codes. This example lists all text files inside the Dropbox folder.

    filecatalog("~/Dropbox","TEXT????")

For new applications we recommend using the Extensions option rather than the Type/Creator codes. Note: You can only use one of these options at a time, you cannot use TypeCreator and Extensions together in the same function.

#### Hidden

The filecatalog( function normally doesn’t include hidden (invisible) files. Set this option to true if you do want them listed.

    filecatalog("~/Dropbox","hidden","true")

#### Shallow

The filecatalog( function normally recursively lists all files and folders in the specified folder. However, if the shallow option is true, the contents of subfolders will not be included. For example, this formula will list only files and folders in the desktop folder, probably no more than a few dozen items.

    filecatalog("~/Desktop","shallow","true")

But this formula will list every file and folder inside every folder on the desktop – possibly hundreds or thousands of files.

    filecatalog("~/Desktop","shallow","false")

If the shallow option is omitted it defaults to false.

#### InsidePackages

The filecatalog( function normally doesn’t include files that are inside packages. Set this option to true if you do want these files included. (If you don’t know what a package is, just leave this option turned off.)

#### HFS

The filecatalog( function normally generates the list of files in UNIX format, like this:

    /Users/bobsmith/Dropbox/Photos/Baby/Photo Jun 17, 10 05 40 AM.jpg
    /Users/bobsmith/Dropbox/Photos/Baby/Photo Jun 17, 10 05 43 AM.jpg
    /Users/bobsmith/Dropbox/Photos/Baby/Photo Jun 17, 10 05 53 AM.jpg
    /Users/bobsmith/Dropbox/Photos/Baby/Photo Jun 17, 10 05 57 AM.jpg

By setting the HFS option to true:

    filecatalog("~/Dropbox","extensions",".jpg","hfs","true")

the result will be in HFS format (the old format used by Mac OS before OS X):

    Mercury HD:Users:bobsmith:Dropbox:Photos:Baby:Photo Jun 17, 10 05 40 AM.jpg
    Mercury HD:Users:bobsmith:Dropbox:Photos:Baby:Photo Jun 17, 10 05 43 AM.jpg
    Mercury HD:Users:bobsmith:Dropbox:Photos:Baby:Photo Jun 17, 10 05 53 AM.jpg
    Mercury HD:Users:bobsmith:Dropbox:Photos:Baby:Photo Jun 17, 10 05 57 AM.jpg

This format can be useful if you have old code that was written to use HFS format.

Note: If the rootpath is specified in HFS format, the result will default to HFS format instead of UNIX format. However, you can always override the default by explicitly setting the HFS option to true or false.

See Also

- aliaspath( -- returns the path an alias points to (or an error if the specified file isn't an alias).
- archivecontents( -- lists the contents of a compressed archive in *.zip*, *.tar.gz* or *.tar.bz2* format.
- bookmarkpath( -- converts saved bookmark data (from the filebookmark( function) into a standard file path.
- bundleresourcepath( -- returns the file path and name of a specified item in the Panorama application bundle.
- choosefiledialog -- displays a modal dialog allowing selection of files or folders.
- choosefolderdialog -- pauses and displays the standard “choose folder” dialog.
- commonpath( -- returns the path for common folders (desktop, library, documents, pictures, etc.).
- compress -- compresses a file or an entire folder.
- copyfile -- copies a file (or folder).
- copyfolder -- copies an entire folder full of files (and subfolders, if any).
- copynewerfile -- copies a file to another name or location. However, the file is only copied if it is newer than the old file, otherwise the destination is not touched.
- copynewerfile( -- copies a file to another name or location. However, the file is only copied if it is newer than the old file, otherwise the destination is not touched.
- copynewerfolder -- copies an entire folder full of files, but only copies newer files.
- dbfolder( -- returns the folder path of the folder the current database is located in.
- dbname( -- returns the name of the current database.
- dbpath( -- returns the HFS path of the folder the current database is located in.
- dbsubfolder( -- returns the path of a subfolder within the same folder as the current database.
- dropfromfinder -- processes any files or folders that have been dropped on a form from the finder.
- dropimagesfromfinder -- processes images that have been dropped on a form from the Finder. The images may be added to new records in the database or put in the current record.
- enclosingfolder( -- takes a full path and filename and returns the name of the folder that contains the file.
- enclosingpath( -- takes a full path and filename and returns the path of the folder that contains the file.
- fileappend -- appends new data to an existing disk file.
- fileattributes( -- returns attributes of the specified file or folder (date, owner, permissions, etc.).
- filebookmark( -- converts a file or folder path into a binary data value that persistently links to the file, even if it is later moved or renamed.
- filedate( -- returns the modification date of a file.
- filedisplayname( -- returns the display name for the specified file or folder.
- fileerase -- erases a disk file or a folder, removing it from the hard disk.
- fileexists( -- returns true if a file exists, false if it does not.
- fileexistspath( -- tests to see if a file exists.
- fileextension( -- extracts the extension (if any) from a partial or complete path and filename.
- filefolder( -- returns the folder ID of the folder that contains the specified file.
- fileidnumber( -- returns the id number for the specified file or folder.
- fileinfo( -- returns information about a file (or folder) on the disk, including the size, creation and modification date and time, type, creator and lock status.
- fileload( -- reads the entire contents of any file on disk.
- fileloadpartial( -- reads a portion of the contents of any file on disk.
- filename( -- extracts the filename from a complete path and filename.
- filepath( -- extracts the path from a combined path and filename.
- filerename -- renames and/or moves a file or folder.
- Files and Folders -- organization of files and folders
- filesave -- saves data directly into a disk file.
- filesize( -- determines the size of any file on disk.
- filesuperdate( -- returns the modification date and time of a file.
- filetime( -- returns the modification time of a file.
- filetypecreator( -- returns the type and creator code of the specified file (if any).
- folder( -- creates a *Folder ID* that unambiguously describes the location of a folder on the hard disk.
- foldercontains( -- checks to see if a folder contains a specified file. See also the pathcontains( function.
- foldercontents( -- returns a list of all of the contents of a folder.
- foldercount( -- returns the total number of files within a folder (including any subfolders).
- folderexists( -- returns true if a folder exists, false if it does not.
- folderpath( -- converts a Folder ID into the HFS path of that folder.
- foldersepchar( -- returns the separator character used between folders.
- foldersize( -- calculates the size of a folder (in bytes).
- fullpath( -- converts a filename or relative path (starting with the : or / symbol) into a full HFS path, including the disk name.
- hfspath( -- converts a UNIX path into an HFS path.
- homepath( -- returns the HFS path of a subfolder of the current users home folder.
- homesubfolder( -- returns the folder id of a subfolder of the current user's home folder.
- hostedfiles( -- returns a list of open databases associated with a specified host (server).
- info("applicationsfolder") -- returns the path to the current user's Applications folder.
- info("applicationsupportfolder") -- returns the path to the current user's Application Support folder (inside the Library folder).
- info("cachefolder") -- returns the path to the current user's Cache folder (in the Library folder).
- info("desktopfolder") -- returns the path to the user's desktop folder.
- info("documentsfolder") -- returns the path to the current user's Documents folder.
- info("downloadsfolder") -- returns the path to the current user's Downloads folder.
- info("dropfiles") -- returns a list of files dragged onto a *Drag Receiver* form object (see Drag and Drop).
- info("foldersepchar") -- returns the separator character used between folders.
- info("libraryfolder") -- returns the path to the current user's Library folder.
- info("moviesfolder") -- returns the path to the current user's Movies folder.
- info("musicfolder") -- returns the path to the current user's Music folder.
- info("panoramafolder") -- returns the location of the folder containing the currently running copy of Panorama.
- info("picturesfolder") -- returns the path to the current user's Pictures folder.
- info("publicfolder") -- returns the path to the current user's Public folder.
- info("tempfolder") -- returns the path to the current user's temporary folder (for files you plan to use only for a short time).
- info("userfolder") -- returns the path to the current user's home folder.
- info("volumes") -- returns a list of all of the currently mounted volumes (disks) on the computer.
- listfiles( -- builds a text array listing the files in a folder.
- listpanoramafiles( -- returns a list of panorama database files in the specified folder.
- listtextfiles( -- returns a list of text files in the specified folder.
- makefolder -- creates a new folder, and if necessary, also creates any enclosing folders needed to create the specified new folder.
- makepackage -- creates a new package, and if necessary, also creates any enclosing folders needed to create the specified new package.
- modifyfileattributes -- modifies one or more attributes of a file (or folder).
- openanything -- opens a document or application.
- openfiledialog -- pauses and displays the standard “open file” dialog.
- openwith -- opens a document with a specific application.
- openwithterminal -- opens an application in a new Terminal.app window (useful for debugging).
- pathcontains( -- checks to see if a folder contains a specified file (or folder).
- pathcontents( -- lists the contents of a folder (specified by a path)
- pathexists( -- checks to see if a path exists.
- pathseparator( -- returns the type of separator character used in a file path (either / or :).
- posixpath( -- converts a path and filename into a POSIX path that can be used as a parameter to a shell command.
- revealinfinder -- reveals a file or folder in the Finder.
- revealmultipleinfinder -- reveals one or more files or folders in the Finder.
- savedialog -- displays a modal dialog that allows a user to specify the name and location of a new file.
- savefiledialog -- pauses a procedure and displays the standard “save file” dialog.
- subfolder( -- returns the folder id of a subfolder of a specified folder
- subpath( -- returns the HFS path of a subfolder of a specified folder.
- tempfolder( -- returns the path to the current user's temporary folder (for files you plan to use only for a short time).
- tildepath( -- converts a path in the current user's folder to tilde (~) notation.
- typecreatorcode( -- returns the 8 character TYPE and CREATOR codes for a filename (if any).
- uncompress -- uncompresses a `.zip`, `.tar.gz` or `.tar.bz2` file into a file or an entire folder.
- unixpath( -- converts an HFS path into a UNIX path.
- unixshellpath( -- converts a path and filename into a POSIX path that can be embedded within the shellscript statement.
- zipcompress -- compresses a file or an entire folder into a zip file (using ditto shell tool).
- zipuncompress -- uncompresses a file or an entire folder from a zip file (using ditto shell tool).

History

Version | Status | Notes
10.2 | New | New options INCLUDEFOLDERS and EXCLUDEFILES.
10.0 | New | New in this version.