News

Version 1.3

See the version history page for details on the latest revision.

Download FindFile OSAX

What Is It?

The FindFile OSAX is a classic Mac OS scripting addition that allows you to gather lists of files and folders starting at any location on any drive connected to your Macintosh, including items in subfolders, no matter how deep. FindFile OSAX is extremely fast and easy to use. You can search for files with the same criteria used in the Mac OS Find File (or Sherlock) utility. FindFile also allows you to press the command-period key combination to halt a search and return you to your scripting. All of this power is available to you from within your AppleScripts, with the ease and simplicity of the english language.

The FindFile Command

The FindFile command uses the following syntax:

Required Syntax:
set theList to FindFile in_folder startHere
Optional Parameters:
[name_contains string]
[filetype_is typeList]
[creator_is creatorList]
[date_created_is date]
[kind_is_application]
[label_is label]
[comments_contain string]
[version_is string]
[maximum_matches integer]
[result_type type]
Optional Boolean Parameters:
[with subfolders]
[with files]
[with folders]
[with events]
[with results]
[with display]

theList

Upon return, this variable contains a list of the items found by FindFile. The list will either be a list of files, folders, or both, depending on what parameters you supply to the FindFile function. Only those items matching the criteria you specify are listed.

in_folder startHere

This is a required parameter. You must supply a starting location for the scan. The value you supply is expected to be an alias, file specification, or a textual full path of the file or folder where the scan is to begin.

name_contains string
name_starts_with string
name_does_not_start_with string
name_ends_with string
name_does_not_end_with string
name_is string
name_is_not string
name_does_not_contain string

This parameter is a string where you supply the file name that FindFile will use to determine which files will be included in your list. This string is not case sensitive. You can think of this parameter as being the same as the filename field in the Mac OS Find File or Sherlock window. If you do not supply this parameter, filenames are ignored during the search.

filetype_is typeList
filetype_is_not typeList

This parameter is a list where you may supply up to 64 file types (4-character OSTypes) which FindFile uses to determine which files are included in your list. The list you supply should either take on the form: {"TEXT","PICT"}, or "TEXTPICT". If you do not supply this parameter, files of any type are included in the list. This parameter has no effect on folders.

creator_is typeList
creator_is_not typeList

This parameter is a list where you may supply up to 64 creator types (4-character OSTypes) which FindFile uses to determine which files are included in your list. The list you supply should either take on the form: {"CWIE","8BIM"}, or "CWIE8BIM". If you do not supply this parameter, files of any creator are included in the list. This parameter has no effect on folders.

label_is label
label_is_not label

This parameter is expected to be a string or a number. If you supply a string, FindFile searches for a file with a label matching this string. Any files with that label are added to the list. If you supply a number, then any file with the corresponding label are included in the list. See the picture below for a list of the label numbers.

You may of course change your label text in the Finder and search for the changed text in your scripts. The index numbers however always remain the same. If you do not supply this parameter, files with any label are included in the list. This option affects both files and folders.

comments_contain string
comments_do_not_contain string

Use this parameter to search for text in the "Get Info" comments of files being scanned.

version_is string
version_is_not string
version_contains string
version_does_not_contain string

This parameter allows you to search for files whos version text matches the criteria you specify. For example, to find all possible beta applications on your hard drive, you might use:

set theList to FindFile in_folder "Macintosh HD:" version_contains "b" with subfolders

kind_is_alias kind_is_not_alias
kind_is_application kind_is_not_application
kind_is_clipping kind_is_not_clipping
kind_is_control_panel kind_is_not_control_panel
kind_is_document kind_is_not_document
kind_is_extension kind_is_not_extension
kind_is_font kind_is_not_font
kind_is_letter kind_is_not_letter
kind_is_sound kind_is_not_sound
kind_is_stationery kind_is_not_stationery

This parameter lets you request certain kinds of files to be returned by FindFile. If you do not supply this parameter, files of any kind are included in the list. This parameter has no effect on folders.

date_created_is date date_modified_is date
date_created_is_not date date_modified_is_not date
date_created_is_before date date_modified_is_before date
date_created_is_after date date_modified_is_after date

This parameter lets you instruct FindFile to only include files created or modified within the date range specified. The date you supply must resolve to a date object as shown below.

If you do not supply this parameter, files with any creation / modification date are included in the list. This parameter works on folders as well as files

maximum_matches integer

This parameter allows you to halt the search after a certain number of matches have been found. This is expected to be a positive number, in integer form.

result_type type

Use this parameter to define the type of items you want FindFile to return in the list of files that match your criteria. Result types currently supported are:

"text" -returns a list of file names that match your criteria
"TEXT" -returns a list of file paths that match your criteria
"fss " -(note the space) returns a list of file specifications that match your criteria
"alis" -returns a list of aliases that match your criteria

More types may be added in the future. This parameter replaces the now obsolete names_only parameter.

with subfolders

This optional parameter tells FindFile to include contents of subfolders in its scan. If the folder pointed to by the starting_at parameter contains subfolders and this option is included in your call to FindFile, the resulting list will contain all items in those subfolders. If this option is left out of the call to FindFile, the resulting list will not include contents of subfolders.

with display

This optional parameter tells FindFile to show its status display while performing the scan. The status display shows information about each file being examined by the osax in real-time:

with files
with
folders

These optional parameters tell FindFile which items you want listed (folders, files, or both). If you do not supply either of these parameters, FindFile defaults to listing files only.

with results

This optional parameter tells FindFile to show the results of a scan after the scan is complete. Elapsed time and number of files searched / found are reported.

with events

This optional parameter tells FindFile to allow other applications to process events during a scan. Be warned that turning this feature on will slow the scan down. It is also not guaranteed to allow full functionality to all other applications during a search. Use at your own risk.

Legal Matters

The FindFile OSAX scripting addition is copyright © 2000-2003 David Blache, Microcosm Software.

This software is offered with no guarantee of support whatsoever (unless freely and unexpectedly given, purely out of the grace and excellent basic goodness-of-heart of said author, who makes absolutely no claims whatsoever to promise same). Nevertheless, and with all serious intentions of being a "fine person of some reasonable degree of earnestness, kindhearted interest, human understanding and worthwhile character," said author would like to hear from you concerning your excellent or other adventures or misadventures with this software.

This software may be distributed with the following requirements:

A) Documentation/text files, copyright notices, contact information, and installer must remain intact and unchanged and be distributed as a whole.

B) Persons or organizations wishing to distribute this software must obtain permission from David Blache, Microcosm Software before doing so.

The FindFile OSAX is shareware. If you find yourself using this software after 30 days of installing it, we ask that you purchase it.

Questions? Bug Reports?

If you have any suggestions for improvement to this scripting addition, feel free to contact . I am always looking for a better way to do things, and I promise to be open to all suggestions. If you encounter problems using this scripting addition, please let me know! It is important to me that my software be compatible and as bug-free as possible! Thanks for your interest in my product. I hope you enjoy using it as much as I enjoy developing it.