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

By Nicholas, 1 December, 2017

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.

Options

Comments

By PaulMartz on Thursday, December 14, 2017 - 22:31

This is a great intro, Nicholas, thanks. I need to keep dipping my feet in the AppleScript water. Eventually I'll get used to it. Learning cool tricks, like the ones you posted, are a great help. And I'm going to follow up with those references you listed, too.

By Ekaj on Thursday, December 14, 2017 - 22:31

Thanks for this blog post. I think it just might come in handy for a real-life journey on which I have just started. That is, a possible new job. I don't want to jinx anything so I'll leave it at that. Those wanting to know more about this possible job offer please contact me privately. But anyway, I always wondered what exactly the AppleScript checkbox in the VO utility was for. I'll definitely be checking out the resources you listed here as well.

By Greg Wocher on Thursday, December 14, 2017 - 22:31

Hello all,
Is there any tutorials out there on how to use the script editor using VO? I am having a bit of a hard time figuring it out. When I open it I am in a list view. I am guessing that this is a list of any recently opened script files. I open up the menu and select new from the file menu and that is where things seem to fall apart. I see absolutely no editor to input scripts. I see something about document actions, script source, description and a couple of other things but no edit area. Any help will be appreciated. Even wen I try and follow one of the tutorials above, what I am getting when I open up the script editor does not match. I am running the latest version of high sierra on a MacBook air.

Regards,
Greg Wocher

By Nicholas on Thursday, December 14, 2017 - 22:31

Hello Greg,
Thanks for reaching out to AppleVis. I do not know about any specific AppleScript guides using VoiceOver. You are right, doing a search on the web only turns up varied scraps of info, but nothing complete with VO instructions.
While I do not have time to do justice to a complete guide at this time, maybe I can help with your current issue, since I am running into it as well. This Mac misbehavior is occurring with TextEdit also, since the update to Sierra. Perhaps it's a feature, not a bug. (cough!)
Sorry for the humor, I know how frustrating these new features can be. Here's what I am finding, it sounds similar to your current situation.
When I launch Script Editor or TextEdit I end up in a list view immediately. This is actually a standard "open file" dialog. For some reason, they think I want to open a file very first thing, which of course, I do not. After first launch, when VO says "list view" I immediately press Command-period, which is like a universal "stop that" keystroke. It should put away the dialog. You can press it repeatedly if needed, sometimes I do it several times just to make a point. :-)
You will be left with no open windows. When trying to navigate, VO will say, Script Editor has no windows. At this point I press Command-n for a new document window.
In Script Editor the new document is split into two sections, an upper window called the script source and a lower window with a "horizontal splitter" bar in between. The lower window will default to show a script "Description" at first. The lower window can be changed farther below to show other info as well.
However, the upper Script Source window is where you want to type your scripts. When navigating to it, VO will say "script source edit text." Interact with this section of the document to start typing your scripts. Be sure to type 'only' scripts in this part of the window. If you are creating "tell blocks" as shown above, make sure you finish them with an "end tell" line, or you will receive an error when compiling. You can always add more indented lines in the middle of a tell block, even if you already typed the end tell line. It doesn't matter until you press command-k to compile. Keep in mind, both window sections are actually part of the same document. I learned this back when I could still see. If they ever change it, I will probably get lost trying to figure it out.
Tip, you can make single line notes to yourself called Comments, directly in your scripts as long as you begin them with two dashes and a space, all typed on one line even if it wraps, as shown below.
-- this is a comment that starts with two dashes and a space, typed as one long single line with no Return in it, except for at the end.
To compile your script or run it, use Command-k to compile and Command-r to run your script. Use the info above to deal with errors and the like.
Once you get hang of the little quirks, scripting can be very rewarding. When ever you get a larger amount of script typed, even if it is not yet fully complete, I highly recommend saving often! Most of the time I will save the script document, as a script (.scpt), before I even type anything. This allows me to use Command-s from that point on, making it easier to deal with scripting as I go. Type some script, compile to verify, press command-s. Then rinse and repeat.
I hope this helps. Feel free to ask any other questions you may have. I know it can be frustrating at first. What I do is walk away for a bit and gather strength, then return with a vengeance. Of course, I sometimes add something special to my coffee which also helps a bit. I wear a baseball cap as well, to cover any new bare patches. :-)
Go Tigers!
Best wishes.

By Greg Wocher on Thursday, December 14, 2017 - 22:31

Hello Nicholas,
Yes this post does help. I did not realize where it said script source was an actual edit field. I have my VO verbosity set to low so when I move to a control I don't et the name of the control and about 3 minutes of help. The control key does not always work to shut up VO. Once I turned my verbosity up to medium, I noticed tit actually said script source edit text. Note to all: When using a new program turn up VO's verbosity while exploring for the first time. It will save some headaches. LOL.

Regards,
Greg Wocher

By Nicholas on Thursday, December 14, 2017 - 22:31

Hi Paul,
Thanks for the great comment. I hope this post helps anyone taking on the beginning learning curve of AppleScript. If you come up with any goodies, please consider sharing. I understand you are taking on several coding adventures at once. Bravo! You must have a lot of stamina. Consider getting a baseball cap. :-)
Thanks again for the comment.
Best regards.

By Nicholas on Thursday, December 14, 2017 - 22:31

Hello Ekaj,

Thanks for the wonderful comment. I hope it helps you on the journey. Of the links I provided, MacScripter is the best over all resource. Definitely bookmark that one. It contains many good resources, guides, downloads and an active forum. Short of plunging in and learning from my constant mistakes, MacScripter was my go to place.
Also, congratulations on the job!
Best wishes.

By Nicholas on Thursday, December 14, 2017 - 22:31

Hello Greg,
Great tip about Verbosity levels. Something I do is, in the VO utility under the verbosity settings there is a disclosure triangle that, once expanded, reveals a table where one can customize the levels for each individual screen element. I usually leave my levels at medium and then go through everything and reduce the levels individually. It’s a bit of work, but worth it. You can set how much is spoken, and what is spoken first. I also turn off hints and announcements, because they drive me crazy. :-)
Best.

By Jeff Crouch on Thursday, December 14, 2017 - 22:31

Hi, this was a awesome post. I messed around with scripting a couple of years ago but got frustrated and walked away from it. This post helped me allot and renewed my energy to start playing with it again. Wile basic, I created a script to open to my college folder which is normally buried under tuns of stuff. I also did one to open text edit and create a new document. Now i'm trying to find a way to script a few keyboard commands that way vo will read the dropbox status. In theory it should work, but I keep getting a application constant or consideration error. I hope you will keep expanding on the topic of scripting. Thank you.

By Nicholas on Thursday, December 14, 2017 - 22:31

Hello Jeff,
Thanks for the great comment. I am glad it inspired you to explore scripting again. It sounds like you're getting a handle on it already.
I think the next post will also involve AppleScript. But, don't tell it I said that! :-)
Best wishes.

By Nicholas on Thursday, December 14, 2017 - 22:31

Hello Jeff,
the script below switches to the Finder and then issues two VO keystrokes, control-option-m, twice. This should land you on the status menus. Many times it is Dropbox. Actually it is the last status menu that you had visited with VO. To set this, press control-option-m, twice. Then use arrows to navigate to the Dropbox menu. Do not enter it. Press the Esc key to leave the status menus. Now pressing control-option-m, twice should place you on the Dropbox menu.

The script keystrokes (presses) the quoted text while holding down several modifiers. Because there are more than one modifier, they are gathered into a List using the {} characters

-- =====

tell application "Finder"
activate
end tell
delay 0.2

tell application "System Events"
keystroke "m" using {control down, option down}
delay 0.1
keystroke "m" using {control down, option down}
end tell

-- ======

By Jeff Crouch on Thursday, December 14, 2017 - 22:31

Hello, thanks for your example. I really appreciate it. I took it and added to it a little. I'll post it below.

By Jeff Crouch on Thursday, December 14, 2017 - 22:31

Like your's it activates the finder, then does control option M twice. I then put in a delay of 4.0 and added a key code for the escape key which is 53.
tell application "Finder"
activate
end tell
delay 0.2
tell application "System Events"
keystroke "m" using {control down, option down}
delay 0.1
keystroke "m" using {control down, option down}
delay 4.0
key code 53
end tell
I'll probably mess around with the 4 seconds, but I don't have anything that is big enough to send to the great cloud in the sky to test it out. :)
Thanks for your help. I really appreciate it.

By PaulMartz on Thursday, December 14, 2017 - 22:31

Hi. Nicholas. Do. You. Know. How.. To. Get. VoiceOver. To. Read. Scripts. More. Naturally.

It seems like, after the compile step, when the script editor goes and formats the script I just wrote, it appears to use different formatting for each word, bold, italic, whatever. And the result is that VoiceOver seems to put a sentence break at the end of each group of formatting. At an extreme, each word is read like a standalone sentence.

Any way to control this? Or maybe just get the script editor to stop formatting the text?

By Nicholas on Thursday, December 14, 2017 - 22:31

Hi Paul,

I've been trying to reproduce this issue, but I'm not getting it. I also recently down-sized to Sierra, so maybe it's a more recent thing? My scripts read normally, compiled or not. I think even before the down size I did not have this behavior.

A few things to check:

This one is obvious, but for general info, make sure you are working inn a AppleScript window, not JavaScript. Choose this on the Language pop up button, just above the script source window.
Then:
In Script Editor, go to Script Editor menu (to the right of Apple Menu), and choose Preferences. On the toolbar, choose, Formatting. This is the only spot I can find for changing the stylization of compiled script. I don't see anything here that would cause hiccups with VO. However, you could set them all to the same font style and see if it helps.
also:
In the VO Utility, Verbosity section, on the Text tab, where it says...
"When text attributes change:" my choice is set to "Do Nothing." I have no idea if that helps, setting it differently seems to work as expected.
One thought, if the above setting was set to Play Tone, and you had sound effects muted, it may cause a pause after compiling, because it is still playing muted effects from every font change?

I can't seem to reproduce it, and there is not much online about VO slowing down in AppleScript.

Only other thing I can think of that has caught me before, sometimes my logic was sound but the script gets caught in a loop. So it seemed like it was not doing anything, but it was actually still running. Everything else I tried to do was very sluggish. Maybe make sure your script is stopped by pressing the big red button, or canceling it with command-period.
Wish I could be more help, but I am not having the issue on this end. Good luck with it! Post a solution here if you find it.
Best regards.

By Nicholas on Thursday, December 14, 2017 - 22:31

Hi Jeff,
Glad to hear it! Adding your own Escape key was nicely done! If needed you could copy the info using,
keystroke "c" using {control down, option down, shift down}
which copies the last phrase spoken by VO.
Then paste it into a textedit file or something.
Glad you're getting a handle on it.
Best regards.