Essential Sub-routines

This section contains dozens of AppleScript sub-routines designed to address a variety of common scripting tasks such as sorting lists of names or parsing HTML files. You can click the small Script Editor icons to open the examples in the Script Editor application on your computer.

What is a Sub-routine?

Sub-routines are valuable tools and a necessary part of every scripter's repertoire. In many respects, a sub-routine is very similar to having an assistant who can perform a specific set of actions to aid you in accomplishing a task.

Sub-routines exist in scripts as sections of specialized AppleScript code placed at the end of your scripts. They are named and function as commands which can be evoked from anywhere within your script.

Most often, sub-routines are created to handle a task which is performed multiple times throughout a script. Instead of inserting a section of AppleScript code many times throughout a script, it is placed at the end of the script as a sub-routine and is called when needed.

NOTE: For a complete overview of all aspects of creating and using sub-routines, refer to the AppleScript Language Guide. The material presented here is a general overview of some standard techniques.

For example, the following script code checks the amount of free space of the startup disk and if it is less than 10 percent of the capacity of the startup disk, will post a dialog to the user alerting them to the situation and asking if the script should continue:

Click to open example in the Script Editor applicationA script that checks to see if a specified percentage of disk space is available:
 

tell application "Finder"
 set the percent_free to ¬
 (((the free space of the startup disk) / (the capacity of the startup disk)) * 100) div 1
end tell
if the percent_free is less than 10 then
 tell application (path to frontmost application as text)
 display dialog "The startup disk has only " & the percent_free & ¬
 " percent of its capacity available." & return & return & ¬
 "Should this script continue?" with icon 1
 end tell
end if

To convert this section of AppleScript code to a sub-routine, it is placed within special opening and closing statements which identify the section as a sub-routine. In this example, the sub-routine is named:

space_check

You can name your sub-routines whatever you like as long as the name contains no special characters or spaces. The sub-routine name is then preceded by the word "on" and followed by an open and close parens. This is the opening part of the sub-routine handler and is placed before the section of AppleScript code we wish to identify as a sub-routine.

on space_check()

To complete the sub-routine, the code segment is followed by a closing statement which begins with the word "end" and the sub-routine name.

end space_check

Here's the previous code made into a sub-routine:

Click to open example in the Script Editor applicationA code segment turned into a callable sub-routine:
 

on space_check()
 tell application "Finder"
 set the percent_free to ¬
 (((the free space of the startup disk) / (the capacity of the startup disk)) * 100) div 1
 end tell
 if the percent_free is less than 10 then
 tell application (path to frontmost application as text)
 display dialog "The startup disk has only " & the percent_free & ¬
 " percent of its capacity available." & return & return & ¬
 "Should this script continue?" with icon 1
 end tell
 end if
end space_check

Calling a Sub-routine

Sub-routines can be called from anywhere within a script. To call a sub-routine, just place the sub-routine name and its following parens on a line in the script. When the script gets to that line, it will jump to the sub-routine and execute its AppleScript code. When the execution of the sub-routine has completed, the script will return to its previous position in the script and continue onward.

There is one special requirement for evoking a sub-routine within a tell block: it must be preceded by the word "my". Doing so identifies to the script that the sub-routine name belongs to the script and not to the object targeted by the tell block.

The following example demonstrates how a sub-routine is called from within a script. Notice that the word "my" is placed before the sub-routine command the second time it is used in the script. This is because the second evocation was placed within a tell block.

Click to open example in the Script Editor applicationA script demonstrating how to call a sub-routine:
 

 tell application "Finder"
 if not (exists folder "EXAMPLE BACKUP") then
 make new folder at desktop with properties {name:"EXAMPLE BACKUP"}
 end if
 try
 repeat with this_file in (every document file of folder "Documents" of home)
 duplicate this_file to folder "EXAMPLE BACKUP" with replacing
 my space_check()
 end repeat
 on error error_message number error_number
 if the error_number is not -128 then
 display dialog error_message buttons {"OK"} default button 1
 end if
 end try
end tell

on space_check()
 tell application "Finder"
 set the percent_free to ¬
 (((the free space of the startup disk) / ¬
 (the capacity of the startup disk)) * 100) div 1
 end tell
 if the percent_free is less than 10 then
 tell application (path to frontmost application as text)
 display dialog "The startup disk has only " & the percent_free & ¬
 " percent of its capacity available." & return & return & ¬
 "Should this script continue?" with icon 1
 end tell
 end if
end space_check

Passing Parameters to a Sub-routine

Sub-routines can receive information passed to them from the script. The passed information can alter the way the sub-routine works or be data that the sub-routine processes and returns to the script.

The following is an example of the previously shown sub-routine now adapted to require a passed parameter. Notice that there is now a variable within the parens: threshold_percentage. This variable will contain the information passed to the sub-routine. In this example, the sub-routine is expecting a numeric value indicating the lowest percentage of disk space available before the sub-routine posts a dialog to the user.

on space_check(threshold_percentage)
 tell application "Finder"
 set the percent_free to ¬
 (((the free space of the startup disk) / ¬
 (the capacity of the startup disk)) * 100) div 1
 end tell
 if the percent_free is less than the threshold_percentage then
 tell application (path to frontmost application as text)
 display dialog "The startup disk has only " & the percent_free & ¬
 " percent of its capacity available." & return & return & ¬
 "Should this script continue?" with icon 1
 end tell
 end if
end space_check

Here is a version of the example script using the new version of the sub-routine. Notice that when the sub-routine is called from within the script, a numeric value is placed within the parens to be passed to sub-routine.

Click to open example in the Script Editor applicationA script demonstrating how to pass data into a sub-routine:
 

space_check(20)

tell application "Finder"
 if not (exists folder "EXAMPLE BACKUP") then
 make new folder at desktop with properties {name:"EXAMPLE BACKUP"}
 end if
 try
 repeat with this_file in (every document file of folder "Documents" of home)
 duplicate this_file to folder "EXAMPLE BACKUP" with replacing
 my space_check(20)
 end repeat
 on error error_message number error_number
 if the error_number is not -128 then
 display dialog error_message buttons {"OK"} default button 1
 end if
 end try
end tell

on space_check(threshold_percentage)
 tell application "Finder"
 set the percent_free to ¬
 (((the free space of the startup disk) / ¬
 (the capacity of the startup disk)) * 100) div 1
 end tell
 if the percent_free is less than the threshold_percentage then
 tell application (path to frontmost application as text)
 display dialog "The startup disk has only " & the percent_free & ¬
 " percent of its capacity available." & return & return & ¬
 "Should this script continue?" with icon 1
 end tell
 end if
end space_check

Returning Data from the Sub-routine

Often sub-routines are used to process passed information and return the result back to the script. To enable this functionality, place in your sub-routine the return command followed by the value to return to the script.

In the example script below, the sub-routine is passed a file name which ends with a file type extension. The sub-routine located and removes the extension and returns the file name without an extension to the script.

Click to open example in the Script Editor applicationA script demonstrating how to return data from a sub-routine:
 

set file_name to "RESTORATION.TXT"
display dialog "The name of the file is: " & ¬
 return & return & file_name buttons {"OK"} default button 1
set file_name to remove_extension(file_name)
display dialog "The name of the file without the extension is: " & ¬
 return & return & file_name buttons {"OK"} default button 1

on remove_extension(this_name)
 if this_name contains "." then
 set this_name to ¬
 (the reverse of every character of this_name) as string
 set x to the offset of "." in this_name
 set this_name to (text (x + 1) thru -1 of this_name)
 set this_name to (the reverse of every character of this_name) as string
 end if
 return this_name
end remove_extension