The following sections describe the commands and classes included with the Sherlock 2 dictionary. Chapter 2, describes application dictionaries if you are not familiar with them.

Dictionary commands

count reference to object

This command counts the number of objects that are specified in its parameter:

tell app "Sherlock 2" to count channels

If you added the code count result to the end of Example 17-1 (just before end tell), then this code would return the number of web sites that the search returned. The return value is an integer.

exists reference to object

If your Sherlock 2 script is running on a different machine than your own, you will have to find out whether a certain channel exists before you specify it in a scripted search. The following example initiates a search only if the "Apple" channel exists on the machine running the script. This command returns a boolean value, true or false:

tell application "Sherlock 2"
   if exists channel "Apple" then
      activate
      (* make sure that you catch any network errors and display the error to the user *)
      try
         search Internet in channel "Apple" for "Mac OS X" with¬
         display
         on error errmesg
         display dialog errmesg
      end try
   else
      display dialog "The Apple channel is not installed."
   end if
end tell

get reference to object

This is the common AppleScript get command, which can be omitted in most cases when you are getting references to Sherlock objects. For example, you can use the code:

tell app "Sherlock 2" to channels

instead of the code:

tell app "Sherlock 2" to get channels

(although the latter phrase is more grammatically correct). Both of these statements return a list of channel objects. An example return value is:

{channel "Files" of application "Sherlock 2", channel "Apple" of 
application "Sherlock 2", channel "Internet" of application "Sherlock2", 
channel "My Channel" of application "Sherlock 2", channel "News" of 
application "Sherlock 2", channel "People" of application "Sherlock 2", 
channel "Reference" of application "Sherlock 2", channel "Shopping" of 
application "Sherlock 2"}.

index containers list of aliases

This command indexes or updates the index of the specified files, folders, or volumes. Using index containers is the equivalent of choosing Sherlock 2's Find:Index Volumes...menu command (just for indexing disks or volumes) or control-clicking a folder or file and choosing Index selection... from the contextual menu. The following example asks the user to choose a folder, using the choose folder osax, then tells Sherlock 2 to index or update the index on that folder. If you want to index several files, folders, or volumes, then use this command with a list of aliases to these indexable objects:

index containers {alias "Macintosh HD:Desktop Folder:today:", alias 
"Macintosh HD:Desktop Folder:scripts:"}.

tell application "Sherlock 2"
   set theFol to (choose folder with prompt¬
      "Choose a folder for Sherlock to index.")
   index containers theFol
end tell

open list of aliases

By passing a file alias to the open command, you can have Sherlock launch another search with search criteria that you previously saved in a file. For example, you can specify detailed search criteria in Sherlock 2's Find File mode or tab, then save this criteria in a file for future searches. To save the search criteria to a file, you use Sherlock 2's FileSave Search Criteria... command. The resulting file has a magnifying glass icon that looks like Figure 17-3. If you double-click this icon, then Sherlock 2 will either launch (if it is not open already) or spawn a new search window and re-do the search based on the search file's criteria. You can also launch the search by using the open command, as in the following example (again, if Sherlock 2 already has a window open, then the open command spawns a new window):

Figure 17-3. A Sherlock 2 search criteria file

tell application "Sherlock 2"
   activate
   open alias "Macintosh HD:Desktop Folder:htm_sher"
end tell

quit

This command quits the Sherlock 2 application:

tell app Sherlock 2 to quit.

run

In most cases it is not necessary to use the run command to execute this program, since targeting Sherlock 2 in a tell statement block executes the program if it is not already open.

search list of aliases

You can use the search command on folders or volumes to find files that contain a specified string, that have content that is similar to other files, or that are returned as the results of an executed search criteria file. The search command has four optional labeled parameters that are described in the following section. You can only use one of the first three parameters. For instance, you cannot use the similar to parameter if you have already specified a search string with the for parameter. If you try to use more than one of the first three parameters, your script will raise an error. This command returns a list of aliases to the files that the search found.

Sherlock 2 searches any folders nested in the folder that is specified by the search command, a handy feature that only requires the script to identify the top-level folder. If the volume containing the folder specified by the search command has not been indexed, then this command will raise an error.

for string

Use this labeled parameter to specify one or more words to search for in the files:

search alias "HFSA2gig:nutshell book:chapters:" for¬ "AppleScript"

If you want to search for more than one word, separate the different words with a space. You cannot use this parameter if you also use the similar to or using parameter.

similar to list of aliases

As opposed to searching with a string of words, you can search for files that contain similar content to the files that you specify in "list of aliases." For example, the following code finds files that are similar to the home.html and search.html files (but these two files have to be previously indexed):

search alias "HFSA2gig:nutshell book:chapters:" similar to¬ {alias 
"macintosh hd:desktop folder:home.html", alias¬
"macintosh  hd:desktop folder:search.html"} with  display.

using alias

You can use a saved file that contains search criteria (see Figure 17-2) instead of specifying a search string to initiate your Sherlock 2 search. For example:

search alias "HFSA2gig:nutshell book:chapters:" using alias¬ "macintosh hd:desktop folder: htm_sher" with display

To save search criteria to a file you use Sherlock 2's File:Save Search Criteria... command (see the open command description). If you use the using parameter, you cannot use the other two labeled parameters: for and similar to.

display boolean

This is a true/false value indicating whether you want the search results to be displayed in a Sherlock 2 window. Usually you will want to display this window, unless you are going to further process the search return value, which is a list of aliases to the files that Sherlock returns as a result.

tell application "Sherlock 2"
   activate
   (* make sure that you catch any network errors and display the error to the user *)
   try
      search alias "HFSA2gig:nutshell book:chapters:" for¬
      "AppleScript" with display
      on error errmesg
      display dialog errmesg
   end try
end tell

search Internet list of strings

A script can search the Web using a string of one or more search words or a saved search criteria file (see the open command description). The following example searches HotBot.com for the Vertech altimeter watch. The "list of strings" parameter is optional, but if you use it, Sherlock 2 limits the search to only the web site(s) identified in the parameter. This parameter is not case-sensitive so you can use "HotBot" or "hotbot." The search-Internet return value is a list of URLs that comprise the search result. Since Sherlock 2 can save search criteria in a file but not the search results itself, this return value allows scripters to extend the application by having the script save the resulting sites to a file or database:

tell application "Sherlock 2"
   activate -- make Sherlock the active window
   (* make sure that you catch any network errors and display the error to the user *)
   try
      search Internet "hotbot" for "vertech altimeter" with¬
      display
      on error errmesg
      display dialog errmesg
   end try
end tell

in channel string

By default, search Internet searches the Internet channel, but you can switch the search to another channel by using this optional labeled parameter.

for string

This optional parameter identifies the words that you are searching for, as in "Vertech altimeter watch." You have to use either the for or using parameters with search Internet, but not both.

using alias

This parameter identifies a search criteria file to use in the search. This is a search query that has been saved in a file (see Figure 17-2 and the open command description).

display boolean

By default, search Internet does not display the Sherlock 2 window or show any results. The web pages that are returned by the search (if any) are returned by search Internet as a list of strings. You can, however, display the search results in a Sherlock 2 window by using display true or with display, as in:

search Internet for "global warming" with display

select search sites list of strings

This command pre-selects a bunch of web-search sites (in the Internet channel by default):

select search sites {"HotBot", "AltaVista"}

The Internet sites that are identified in the "list of strings" parameter are case-sensitive, so {"HotBot", "AltaVista"} puts checkmarks next to only those sites in the Internet channel, but {"hotbot", "altavista"} does not select those sites.

in channel string

You can optionally specify the channel in which to select the search sites. The following example first selects the Apple Tech Info Library site in the "Apple" channel then searches only that site:

tell application "Sherlock 2"
   activate
   select search sites {"Apple Tech Info Library"} in channel¬
   "Apple"
   (* make sure that you catch any network errors and display the error to the user *)
   try
      search Internet in channel "Apple" for¬
      "Mac OS X public beta" with display
      on error errmesg
      display dialog errmesg
   end try
end tell

set reference

A script can set one of Sherlock 2's properties with this command:

set current tab to Find by Content Tab

See the application class description.

to anything

Use this labeled parameter to specify the value of a property:

tell app "Sherlock 2" to set current channel to "Apple"

Provide the keyword to followed by the property value, which in the example is the string "Apple." anything is an AppleScript data type that can be, well, anything. In other words, it can contain a string or a number or a constant, among other value types.

Dictionary classes

application

This class represents the Sherlock 2 application. It has several channel elements, which a script can obtain as a list value with the code:

tell app "Sherlock 2" to set allch to channels

In this sample code, the allch variable holds the list of channel objects. The Sherlock 2 app has three properties, two of which are settable:

set current channel to channel "People"

The following are application elements:

channel

The Sherlock 2 app has several channel elements, which are returned as a list value by code such as:

tell app "Sherlock 2" to get channels

An example return value is:

{channel "Files" of application "Sherlock 2", channel "Apple" of 
application "Sherlock 2", channel "Internet" of application "Sherlock 2", 
channel "My Channel" of application "Sherlock 2", channel "News" of application
"Sherlock 2", channel "People" of application "Sherlock 2", channel "Reference"
of application "Sherlock 2", channel "Shopping" of application "Sherlock 2"}

Each member of this list is a channel object; see the channel class description.

The following are application properties:

current channel reference

A script can find out and optionally change the currently active channel with this settable property. An example is:

set current channel to channel "People"

all search sites reference (read-only)

This property returns the Internet search sites as a list. An example return value is:

{"Aladdin Systems", "Aladdin Systems: Frequently Asked 
Questions", "AltaVista", "Apple iReview", "Best Site First", "CNET", 
"CNET Download.com", "Direct Hit", "Excite", "GoTo.com", "HotBot", 
"Infoseek", "LookSmart", "Lycos", "Rolling Stone"}.

current tab Find File Tab/Find by Content Tab/Search Internet Tab

You can set the current tab or focus of the Sherlock 2 window with code such as:

set current tab to Search Internet Tab

However, Sherlock 2 in Mac OS 9 tends to return Find File Tab from the current tab property, no matter which of the window elements (Search Internet or Find File) currently has the focus.

channel

This class represents a channel object, which is a representation of the various areas of the Web or your filesystem that Sherlock will search. The channels are depicted in the Sherlock 2 window as icons along the top of the frame (see Figure 17-1). When you select one of the icons (e.g., "Internet," "People," "Shopping"), Sherlock 2 displays the web sites, disks, or folders that it will search. channel objects are returned by the Sherlock 2 application object's current channel property, for instance. A channel object is identified by using the keyword channel followed by its string name:

channel "People"

The following are channel properties:

all search sites reference (read-only)

A script can obtain all the search sites attached to a channel by getting the channel's all search sites property value:

get all search sites of channel "Apple"

An example return value from this code is:

{"Apple iReview", "Apple Macintosh Products Guide", "Apple¬
Tech Info Library", "Apple.com"}

name international text (read-only)

The name of a channel is a string:

channel "Internet"