Yo, Human! Mac Scripting, “Hello World”: Accessing Life with Adaptive Technology

Speaking Up with AppleScript

Once You gaze into the System, the System also gazes into You! :-)

Fair warning! Any programming and scripting adventures can at first, be; very frustrating, extremely rewarding, can sink you into the depths of a learning curve for a long period of time, expand one's thinking patterns far beyond normal, cause one to pull one's hair out, cause one to become much faster and productive on their computer, can at times force one to restart their system frequently, and quite possibly be the most amazing and fun thing you have ever done. Enter at your own risk, for once the journey has begun the "you" you have always known may never return.

Disclaimer: Apple, AppleVis and Nicholas are not responsible for anything you may do to, with or for, your computer. If you enter the world of scripting or programming, whatever you create you own completely yourself, failures or successes. Such is the fate of any developer, regardless of the platform or experience . Having a back up of your important stuff is a very good idea.

That is not to say that it is overly dangerous, or that there is no help out there, many resources exist that can assist on your journey. I will include any links I can find near the bottom of this post. I can say, in the twenty-five years that I have dabbled with AppleScript, I have never had to reinstall any software because of my scripting. Admittedly, I am more of an advanced dabbler, but I am certainly no expert. I have personally enjoyed the easier scripts that help automate my systems. I am perfectly happy staying at that level. Dabbling with easy AppleScripts has expanded my thought patterns and taught me much about Mac OS and my computer that I might never have learned otherwise. It has been and continues to be, one of the most frustrating, gratifying and amazing adventures I have ever embarked upon. Really!

Now that I have completely scared the pants off you, put something comfortable on, grab some coffee or tea and lets get started.

In the Beginning

In the traditional methods of teaching any programming, the first project is always, showing how to create something that presents two simple words on the computer for the user to see. These traditional words are, "Hello World." In keeping with Apple's usually non-traditional method, and considering the AppleVis community, there will be a slight variation in our own approach. Rather than printing the words on the screen, we will have the computer actually 'say' the words instead. I know what you might be thinking, programming is complex. However, the above project is actually much easier than one might think. When I began my own scripting adventures with AppleScript in the early nineties (Was it System 7?), this is also how I began.

AppleScript is known as an 'English-like' language. Meaning, at the dabbler level, most commands and blocks of script are typed with easy to understand words that read just like the English language. So the benefit is having an easier to understand process from beginning to end. Just looking through your script pretty much tells you what it will do, and to what. Although, there are many levels of expertise beyond my dabbles. I find some sneaky scripts online that completely baffle me, and look more like math equations than anything. It's okay though, this is normal and only shows how much room for advancement actually exists.

The Script Editor IDE (an Irresistible Daring Environment)

Just kidding, actually IDE is Integrated Development Environment. The Script Editor, also called the AppleScript Editor in earlier Operating Systems, can be found in the Applications/Utilities folder. You can get there in the Finder from the Go Menu and choose Utilities. Once opened the Script Editor is, for all practical purposes, a fancy text editor. But, don't tell it I said that. (Ahem!)

The Script Editor contains two main windows and a toolbar. The main upper window, also called the Script Source window, is where you type the scripts. The lower window is for various results from running your scripts. The lower window can be largely ignored for now. Everything we do in this post will take place in the main window and on the toolbar.

The Toolbar. (Don't Push the Big Red Button!)

The Toolbar has two main buttons that will be used repeatedly, the Compile button (Command-k) and the Run button (Command-r). Actually, I don't think either of them are red. The Compile button is kind of like a spell check for scripting. It doesn't check your spelling as much as the syntax or structure of your scripts. If something doesn't make sense to the compiler, you will receive a dialog warning. At first, these dialogs can also be mostly ignored. Just click OK to dismiss it. Then look at your script for errors. Scripts can be very easy to read, but are still somewhat fussy on how they are typed. The Run button will attempt to run your script from the Script Editor. To test my scripts from the Editor, in case I typed something weird I do the following; I navigate to the Toolbar, click the Compile button, then Run! :-)

That Crafty Compiler

The Compiler tries to compile your scripts into a language the Mac understands. If it is successful your script will become colored in a way that makes the logic more obvious. If needed, compiling will also auto-indent where appropriate. Sometimes it doesn't succeed and throws an error. I blame the Compiler for this! At least until I find the error in my script. Oops. :-)

Sometimes the Compiler will try to pull a fast one! Sometimes when it 'does' succeed, your script still won't work the way you expect. This is usually because the logic in your script is doing something other than your intention. There could be many reasons for this. Scripts are very chronological, from top to bottom. Make sure things are typed in the order you wish for them to occur. Scripts are also very fast. Sometimes a compiled script will still not function the way you expect because of the speed at which it is being executed. There is a "Delay" command that we will use below that can make your script hesitate and let your system catch up.

Errors are Highly Illogical

Actually, errors are normal and help you correct your scripts as you go, so don't be too frustrated when they occur. The most common errors are from typos, incomplete scripts, or logic that doesn't make sense to the Compiler. (Shh! Don't tell it that I said that.) Anyway, we will be sticking with very simple script examples farther below, you should be able to compare easily to your own.

For instance, in one script I tell TextEdit to open. Then the next command tells it to do something to the blank document. Running the script loads TextEdit, then gives the system error sound, then the blank document appears, but does not do anything else. My problem was that the 'do something' part was being executed before the document was fully on the screen. (Sheesh, talk about picky!) Using a Delay command between the two others fixed the issue. My logic was sound, the script just needed tweaking for the way my computer responds. I guess even programs need to slow down once in a while.

Run Away!

Compiling will not run your script. The Run button on the toolbar will attempt to run your script from inside the Script Editor. If it is uncompiled, it will try to Compile first, then run. Hey, get back here.

Your saved scripts (.scpt), can be run from many areas in the OS, not just the Script Editor. The AppleScript Status menu, a custom Keyboard Commander shortcut, as your own saved application, drag a script file to a customized toolbar, a service on the shortcut menu, a folder action, even a custom Dictation command to name a few.

The secret Status (menu.)

To run them from the Scripts Status Menu, first we have to unhide the menu. Open the Script Editor and navigate to the Script Editor Menu and choose Preferences. In the "General" section, check the check box "Show Script menu in menu bar." No more hiding for you. Then navigate to the Status Menus and click the "AppleScript" Menu to look at the default scripts that are available. The Status menus are on the top right of the main menu bar. You can get there using VO by pressing Control-Option-m, then press it again.

To add your own scripts to this menu, first they must be compiled and working. In the Finder click the Go menu and choose Library. Then find and open the scripts folder. You can make your own folder structure here. Then copy/paste in your script. They will appear in the AppleScript Status Menu at the bottom. Maybe some day I can work my way to the top. ;-)

The "Hello World"Script

When you open the Script Editor, Depending on your settings, you may receive an Open File dialog. Press Command-. (period), to cancel the dialog, then press 'Command-n' for a new document. Or do what ever you need to get a new empty script window on the screen. Navigate to, and interact with the Script source window. Then type the script below. You can sometimes copy and paste scripts from the web, but this can also cause issues picking up hidden and special characters which will throw one of those lovely errors on the screen. For easier scripts, it is always safer to type them.

Type the line below exactly as you find it, no extra spaces or punctuation.

say "Hello world!

Once you have it typed in, you are ready to compile. What? That's it? Yup, that's it! Welcome to your first script. Clicking the Compile button on the Toolbar will check it and if successful, colorize the script. For some of us the coloration does not matter, but the fact that no error appeared is the important part. If you did receive an error, dismiss it and go over your script with a fine-toothed comb. Make sure there is a space between the word 'say,' and the quoted text. Also make sure the quoted text has no additional quotes, only the two outside quotes. Make sure there are no extra characters at the end, beyond the quotes, especially punctuation. Also make sure you are typing plain quotes, not the special quotes that are left or right. VO should say only Quote, not, left-double-quotation-mark. If you are typing into Script Editor, you should already be using plain quotes by default. I like to type some longer scripts into TextEdit, but I have to use plain text documents or I get the fancy stuff that Script Editor doesn't like.

Next click the Run button and listen. Your script will use the Mac's text-to-speech engine and 'speak' your message using the default system voice. If you hear "Hello World," then your script is working. This is a good time to save your script somewhere. Save it as a script '.scpt'. I like to make a Scripts folder on my desktop to stash my scripts. It becomes a good place to put resource materials as well. Everything is nice and handy for my scripting adventures.

Now play with it some, type something else between the quotes. Remember to be careful as stated above, no extra quotes, no extra stuff outside the quotes except the word say. You can use standard punctuation inside the quotes, but avoid stuff like slashes, colons, semi-colons, etc. You can type as much as you wish between the quotes, even multiple sentences or entire paragraphs. Then compile.

Click the Run button and let her rip. It should speak your entire text, what ever is between the quotes. Once you are done playing, let's change it up a bit. Delete your current script, or start with a new script window. Type the following script below, being careful just as we did earlier. Remember with the level we are currently at, lines of script have no punctuation at the end, or anywhere except inside the quotes.

say "Hello world!" using "Alex

Compile and Run the script. It should sound identical to the previous script if Alex is your default system voice. The one-line script above does the same as our earlier script, but designates the voice "Alex" in quotes at the end. The 'using' command allows one to use any voice that is already downloaded and installed on your system. You must use the exact spelling of the name, in quotes, without any punctuation.

Let's add to it a bit. Below is a three line script that uses the voices "Alex" and "Fred." Or you can use any two Voices that are already installed. The first lime is a say line, the next one uses the 'Delay' command. Then the third line uses the say command again, with a different voice.

say "Why did the chicken cross the road?" using "Alex"
Delay 1.5
say "Sheesh! You are supposed to be the new fancy voice and you are still telling old chicken jokes?" using "Fred

The three line script above uses Alex to speak your text, then waits 1.5 seconds, then speaks again using the Fred voice. Using this same method, you could keep going with any voices on your system, creating an entire dialogue with multiple speaking parts, adjusting the timing using the Delay command. I once created an entire comedy routine this way. It wasn't very funny, but I sure learned a lot. :-)

Tell the Whole Block

So far we have typed in single lines of code. Another method is to send multiple lines of code to a specific application. These are called "tell blocks." You start by addressing a application by name, then send several lines of code that are indented underneath. Then finish it off with an unindented line at the very end. Below is an example that launches Safari.

tell application "Safari"
    activate
end tell

The 'tell' part is not indented. Any lines underneath are indented with one Tab spot. Then the final line is not indented. So we start by telling the system that we are instructing Safari to do something on the following lines, which are all indented. Then we finish it off by telling the system that we are done addressing Safari specifically, with an 'end tell'. The Activate command will launch the application in the first line, or if it is already running, bring it to the front.

There are other 'blocks' of code for various functions, all of them finish off with an End statement of some sort. Tell blocks finish with 'end tell'. 'If' blocks finish with 'end if'. Repeat blocks finish with 'end repeat'. etc. All of them have indented lines in between the beginning and ending lines. In the current Script Editor, after typing the first indented line, it will start auto-indenting until you force it to stop. This is very handy when typing longer blocks of code. To stop the behavior, simply delete the auto-tab and type your end statement.

Since this post is getting rather long, we will wrap it up here. One more script for an early Christmas present, for any who wish to type it in. Remember to use one Tab spot for indents.

The script below requires an open TextEdit document with something in it, then open Script Editor and type in the following script exactly as you find it. Note, it contains two variables that each look like two words stuck together, "theText" and "wordAmount". Type them the same way. A fun side note, this use of typing the name of a variable is known as "Camel case" because the second word of the variable is capitalized, looking like the hump of a camel. :-)

The script below also has a small phrase in parenthesis, make sure to include them.

tell application "TextEdit"
    activate
    set theText to text of front document
end tell
delay 0.5
tell me
    activate
    set wordAmount to (count of words of theText)
    display dialog "Word count: " & wordAmount
end tell

Running the script will pull TextEdit to the front, get a word count from the open front document and stash it into the variable theText. It waits a half of a second, then switches back to itself and retrieves a word count which it stashes into the variable wordAmount. Then it puts a dialog on the screen that shows the word count by sticking the variables and a message together using the & symbol. The dialog can be dismissed by clicking the OK button, or the Cancel button, or by pressing Return on your keyboard. It is a very handy script, I use it a lot.

Feel free to save it on your system for future use. You can save it as a script that will open into Script Editor, or save it as an application that will simply run and do its thing. When I save mine as an app, I also like to save a script version first for easy editing into new versions.

There you have it, the scripting door is cracked open a little. There is an entire world waiting on the other side. Perhaps next month's blog will dive into another whole area of scripting, issuing keystrokes and other events through your scripts. This can include any VO keystrokes as well. As you learn more on your own, especially for those of us that cannot see the screen, remember to use the 'say' command for confirmation of what is happening while your script is being run.

Keep in mind, no matter how fussy your scripts end up being (don't tell the Compiler I said that,), it is really about one important idea:

All of our cool digital stuff that we work with, play with and enjoy, is all about "Living." Live well!

Helpful resources:

AppleScript: Beginner's Tutorial - macOS Automation
https://macosxautomation.com/applescript/firsttutorial/index.html

AppleScript: Overview.
https://developer.apple.com/library/content/documentation/AppleScript/Conceptual/AppleScriptX/AppleScriptX.html

Introduction to AppleScript Language Guide - Apple Developer
https://developer.apple.com/library/content/documentation/AppleScript/Conceptual/AppleScriptLangGuide/introduction/ASLR_intro.html

MacScripter: Forums and Tutorials. Highly recommended!
http://macscripter.net

AppleScript - Wikipedia
https://en.wikipedia.org/wiki/AppleScript

AppleScript is an open-ended language and many find new ways of using it to help automate their systems. There are many AppleScript sites on the web, I invite you to include your own scripts and links in the comments below. Let's see if we can crack that door a little farther open. :-)

Portions copyright Apple, Inc. All rights reserved.