Sherlock 2
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.
reference
to objectThis 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
.
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
reference
to objectThis 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"}.
list
of aliasesThis 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
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
This command quits the Sherlock 2 application:
tell app Sherlock 2 to quit.
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.
list
of aliasesYou 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 aliasesAs 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 stringsA 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
list
of stringsThis 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
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.
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"