Name

Sherlock 2

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 File Save 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):

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.

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.

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.

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:

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

The following are application properties:

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: