You can use three shell commands to connect a shell script to AppleScript:

osalang is the command that enables you to see what OSA languages are installed on a given Mac. If I run osalang with the -L switch on the Mac on which I'm writing this chapter, which gives me all the available languages and their capabilities, I get the following:

[Aurora:∼] jwelch% osalang -L
Jscr LNS  cgxe-v-h  JavaScript (JavaScript Scripting System)
asDB asDB cgxe-v-h  AppleScript Debugger (Script Debugger's AppleScript debugger)
ascr appl cgxervdh  AppleScript (AppleScript.)
scpt appl cgxervdh  Generic Scripting System (Transparently supports all installed
OSA scripting systems.)

The output shows that I have a few different potential languages with different capabilities. The capabilities of the languages translate as follows:

c     compiling scripts.
g     getting source data.
x     coercing script values.
e     manipulating the event create and send functions.
r     recording scripts.
v     ``convenience'' APIs to execute scripts in one step.
d     manipulating dialects.
h     using scripts to handle Apple Events.

In other words, by using osalang and grep, you can test for a given language or set of capabilities. For example, to look for JavaScript and get its feature set, you use the following:

osalang -L|grep "JavaScript"

The preceding command would return the following:

Jscr LNS  cgxe-v-h  JavaScript (JavaScript Scripting System)

Therefore, if you need a specific OSA language, osalang is a handy way to test for that.

osacompile is the second part of the command line AppleScript trio, and a very powerful one. This command enables you to create a compiled script, or script application, from shell input or a text file. You can also specify the OSA language you wish to use; in fact, you can even use different languages depending on the capabilities of the system you're running. For example, you could test for Perl and JavaScript while using AppleScript as a fallback by taking the output of osalang and using that to test for the languages you want. osacompile has a nice set of switches that give you a lot of power (see the man osacompile page for full details), but the following list shows the major switches:

The final part of the AppleScript shell command triumvirate is osascript, which is the complement to osacompile. osascript executes a given script file or input command but doesn't create a script. It has similar flags to osacompile; in fact, the -l and -e flags are identical. The -s flag is for setting options that specify how the script output and errors should be handled. Normally, the output of a script is in human-readable format, so the command osacompile -e 'set foo to {"listitem1","listitem2"}' followed by osascript a.scpt returns listitem1, listitem2. However, if you use the s option for the -s flag, osascript -s s a.scpt, on the same script, you get the results in the "real" form, which could be compiled into another script: {"listitem1", "listitem2"}. Normally, osascript passes errors to stderr, not the screen. If you want to see runtime errors (not compile errors; those always go to the screen), use -s o with osascript.

There are some limitations with osascript and osacompile. First, you can't play outside your sandbox. If you want to play with things that are above your authentication level, it's not going to work unless you use sudo or su to run the command. Second, you can't use osascript to run scripts that require user interaction. Therefore, while you can use osacompile to create scripts that require user interaction, you can't use osascript to run them. Considering that user interaction in AppleScripts happens outside of the command-line environment, this makes sense. However, you could use the open command, as in the alarm-clock example shown earlier, to run an AppleScript application that requires user interaction. Finally, you can't get too interactive with these commands. The only result you can directly get from an AppleScript is the last one. For anything else, you'll need to have the script write results to a text file.

While going from shell to AppleScript is really cool, it's only half the story. You can run shell scripts directly from AppleScript via the do shell script command. do shell script is a fairly self-explanatory command, with a limited set of parameters. From the Standard Additions dictionary:

do shell script string  -- the command or shell script to execute.  Examples are
'ls' or '/bin/ps -auxwww'
[as type class] -- the desired type of result; default is Unicode text (UTF-8)
[administrator privileges boolean] -- execute the command as the administrator
[password string] -- use this administrator password to avoid a password dialog
[altering line endings boolean] -- change all line endings to Mac-style and trim a
 trailing one (default true)
[Result: string]  -- the command output

There's not a lot to do here, parameterwise. You can specify how you want the result. You can run the shell script as root, but if you do, you have to provide a password. You can enter the password in more than one way: as part of a displayed dialog box (somewhat secure), embedded in the script (not secure at all, not even if it's run-only), or by fetching the password from the user's secure password storage, aka the Keychain or the Keychain Scripting application. (I'll leave the Keychain scripting up to you as an extra-credit trick, but it's really cool, and the only way to get the password is to have an event tap or read it directly from RAM. If someone has cracked your machine to that level, you have greater problems than a shell script.) Altering line endings enables you to have the script output results as a Mac-style string, not a Unix-style string. Change that setting to false for Unix line endings.

This feature is a huge hit among the AppleScript community, because it enables them to leverage the strengths of other languages without having to resort to bizarre workarounds. Therefore, if you need high-level text manipulation, instead of trying to do it in AppleScript (a tedious proposition), you can use do shell script, and connect to a Perl or shell routine that will manipulate text far faster and more efficiently. It's also handy for doing things when you don't feel like waiting for others. For example, until quite recently, Virex, an antivirus utility for the Mac, couldn't automatically scan items. You had to manually invoke the scan engine in the UI or use the shell command, vscanx, manually or via cron. Of course, that's not the same as autoscanning a file as soon as it's downloaded. Therefore, I used do shell script to create a routine for scanning files with vscanx.

First, I set a property that contained the command I needed with all the arguments that I wanted to use:

property theScan : "/usr/local/vscanx/vscanx --allole --dam --delete --one-file-
system --recursive --secure --summary "

This command scans every kind of file (--secure, --allole) inside of any folder it's presented with (--recursive), cleans all macros from a potentially infected file (--dam), deletes any infected file (--delete), resides on a single file system (--one-file-system), and prints a summary to the screen of what it found (--summary). (Note that because Unix can make remote file systems look like a part of the local file system, and because the AFS distributed file system can make entire global networks look like part of the local file system, the --one-file-system option is important.) This way, I could use theScan instead of the full command line and parameters.

Next, I created another property that would use grep to scan the results of the viral scan for an infected file result:

property theGrep : "|grep "Possibly Infected""

That was only part of it, however. AppleScript in OS X uses something it calls folder actions, commands that run as part of something that happens to a folder, such as adding a file to a folder—that is, downloading a file to the Desktop. Using that and some do shell script wizardry, I built an autoscan system for Virex that did not need to interact with OS X at the kernel level (as do most of these systems). It was fast, and I had it working a year before McAfee was able to get a stable version of Virex that had autoscan out the door. The full code, with explanations, follows:

property theScan : "/usr/local/vscanx/vscanx --allole --dam --delete --one-file-system --recursive --secure --summary "

The property statement uses a variable for the scan command with the full path to vscanx; that way, I didn't have to rely on user shell configurations.

property theGrep : "|grep "Possibly Infected"" --this will check for infected file result

The preceding line checks for the infected file indicated in the summary.

property theResult : ""

theResult is a placeholder text variable.

property theMessage : ""

theMessage is a placeholder text variable.

on adding folder items to this_folder after receiving added_items

This line is part of the folder action handler (AppleScript lingo for subroutine) that deals with adding items to a folder. this_folder and added_items are standard names in this statement, and almost every example of this kind of folder action uses them. I used an example from Apple's AppleScript web site to help me out on this.

tell application "Finder"
        set the folder_name to the name of this_folder
  end tell

Because the Finder is the standard file and folder manipulation application, I use its capabilities to get the name of this_folder and put that in folder_name.

-- find out how many new items have been placed in the folder
  set the item_count to the number of items in the added_items

The preceding step gets the number of items that have been added to the folder and puts that number in item_count.

repeat with x in added_items

repeat loops are AppleScript's version of for-next and while loops. In this case, I am using the number of items in added_items as the control for the loop; and for each iteration, I assign a new item to x.

set theFileInfo to info for x --get info for the downloading file(s)

info for is a record (a list where each item has a label) that is an array of properties for a file, so I put that record into theFileInfo.

set theBaseSize to size of theFileInfo --get initial size

I want to get the current size of the file and use it as a baseline (I'll explain why in a second).

delay 3 --wait 3 seconds
          set theFileInfo to info for x --get info again

This code refreshes the information in theFileInfo.

set theCompareSize to size of theFileInfo --get a newer size

This line gets the most current size of the file.

repeat while theCompareSize ≠ theBaseSize --if they don't equal, loop until they do

As of Panther, Mac OS X 10.3, it's hard to tell when a file is still downloading. While the Finder does have a busy flag, it's not used if you are transferring files, say, via ftp, sftp, or some other command-line option. (Well, it may or may not, but as of version 10.3, it's not reliable). Therefore, to work around that, I wrote a loop that compares the starting size with the current size every three seconds. Even on a slow link, the size should change by a byte or two in three seconds. If they aren't equal, theBaseSize is set to theCompareSize, the system waits three seconds, refreshes theFileInfo, gets a new theCompareSize, and checks again. Eventually, the two sizes will match, and as far as the script is concerned, the download is done. The next five lines handle this:

set theBaseSize to theCompareSize --new base size
delay 3 --wait three seconds
set theFileInfo to info for x --get info
set theCompareSize to size of theFileInfo --get a newer size
          end repeat --once the sizes match, the download is done

          set thePath to " "" & (POSIX path of x) & """ --this quotes the file
path so that odd characters are handled correctly

In Mac OS X, path delimiters aren't a / (slash) character but a : (colon). The shell environment only uses slashes, so to get around this, use the POSIX path command to get the shell-compatible path of the file from the Mac OS X path. Because it needs to have quotes in it, I insert those by escaping them with the " character:

set theCommand to theScan & thePath & theGrep as string --build the
entire command, but only caring if infected files are found

Now build the command. Take the theCommand variable, set its contents to the theScan variable concatenated with the thePath variable I just created, and then concatenate them with the theGrep variable. And make sure the entire thing is a string, as that's what's needed in the next step:

set theResult to do shell script theCommand --run the command

Run vscanx against the current item in added_items, and set that to text:

set theTextResult to theResult as text --text version of the result

Even though this is normally a string, I like to be sure, so I use the as text coercion:

set oldDelims to AppleScript's text item delimiters --temp store Applescript
current delimiters

Because the result is going to contain a lot of words and spaces (and I only care about one thing), I'm going to parse it. Normally, Apple uses the null character as a text delimiter. I want to use a space, so I first store the current delimiter in a variable for safekeeping. oldDelims is traditionally used for this.

set AppleScript's text item delimiters to " " --use spaces as the current delimiter

The preceding line sets the text item delimiters to a space.

set theNewResult to (every text item of theTextResult) --this turns the text into a
list, with the number at the end

Now turn the result from a single text line to a list of words. When vscanx returns a summary, the number of items found is always the last word/item in the line. Therefore, I turn this into a list, and the last item in the list is going to indicate how many infected items were found and deleted.

set theTest to the last item of theNewResult as number --since the last item is the
number of possibly infected files, let's treat it as one

Remember that in a string, a number character is just that: a character. It's not a number, but we need it to be one, as numerical tests are really easy and reliable compared to text tests. Set theTest to the last item of the newly created list from the summary to force, or coerce, that value to be a number.

if theTest ≠ 0 then --only display a dialog if possible infections are found

As long as it's not zero, it's a positive integer. (If it returns a negative, then vscanx is way buggy, and we can't possibly work around that here anyway. In any event, I've never seen that happen or heard of it happening.)

set theTest to theTest as text --display dialog only likes text

A nonzero return indicates a possible bad virus, and because the file's already been deleted, I should probably tell the user. To do that, I need a display dialog step, and that requires text, so I coerce theTest back to a text variable.

display dialog theTest & " possibly infected files were found in
" & thePath & ", and deleted!" --give the user the number of infected files and
location

The preceding code tells the user how many infected files were deleted and where they were. I put this in the repeat loop, so if users wanted to kill the scan on the spot, they could by hitting the Cancel button in the dialog box. It creates an error that kills the script. It's a bit abrupt, but it works well here, and it definitely stops the script from running, which is what I want.

end if

This is the close of the if statement, aka fi in shell. AppleScript closes things with an end whatever. More verbose, but in many cases clearer, and much nicer if you're a tad dyslexic.

set AppleScript's text item delimiters to oldDelims

Because I can't always count on the script's ending cleanly, I restore the delimiters to the state they were in before each iteration. I haven't seen that this creates a noticeable slowdown.

--display dialog theResult --add some grep routines to parse for actual infections

The preceding line is a reminder of stuff I should do one day.

end repeat

This line closes the repeat loop.

end adding folder items to

Finally, the preceding line ends the folder action.

This is a great, albeit not glamorous, use for do shell script, and it shows how it can be a force multiplier for AppleScript. I could use the GUI Virex application here, but if it's not running, the user has to deal with it popping up, eating CPU even in the background, taking up space in the Dock, and so on, even if there's no virus to be found. This way, everything is scanned (regardless of the folder to which you attach this action), and the only time the user is bothered is when a virus is found. Because this happens within three seconds of the file's completing a download, it's unlikely that the user will be able to open the file before the scan happens. True, you have to manually assign this script to every folder on which you want it to run, but it enabled me to enjoy autoscan in a safe, nonkernel patching manner a year before McAfee could offer it. Viruses don't pose the same worry on the Mac as they do on Windows, so this is a more than acceptable level of virus protection for the platform.

Like using osacompile and the others, do shell script has some limitations. First, it's a one-shot deal. You can't use it to create user or even script interactions between shell and AppleScript. The command runs, and you get a return. It's no more interactive than that. You can have the shell script write results to a text file and use AppleScript to read those, but that's it. Second, unless you use an ignoring application responses block, as in the iTunes alarm-clock example, AppleScript will pause script or application execution until the script ends. If you use ignoring application responses with do shell script, you can't get the result of the do shell script step with any reliability. Finally, do shell script uses sh for its environment, and you can't change it unless you include the specific shell in the do shell script statement or in the script you're running. For full details on do shell script, read Apple Technical Note TN 2065, available at http://developer.apple.com/technotes/tn2002/tn2065.html. It is the authoritative answer to almost every do shell script question you'll ever have.

There, in a nutshell, are the basics of AppleScript and shell interaction. You can do a lot more with these two very powerful languages, but I leave that for your own inventive/demented needs.