AppleScript Language Guide English Dialect Apple Computer, Inc. Helvetica and Palatino are registered Even though Apple has reviewed this © 1996 Apple Computer, Inc. trademarks of Linotype Company. manual, APPLE MAKES NO All rights reserved. FileMaker is a registered trademark WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH No part of this publication or the of Claris Corporation. RESPECT TO THIS MANUAL, ITS software described in it may be ITC Zapf Dingbats is a registered QUALITY, ACCURACY, MERCHANTA- reproduced, stored in a retrieval trademark of International Typeface BILITY, OR FITNESS FOR A PARTIC- system, or transmitted, in any form Corporation. ULAR PURPOSE. AS A RESULT, THIS or by any means, mechanical, Microsoft is a registered trademark MANUAL IS SOLD “AS IS,” AND electronic, photocopying, recording, of Microsoft Corporation. YOU, THE PURCHASER, ARE or otherwise, without prior written ASSUMING THE ENTIRE RISK AS TO permission of Apple Computer, Inc. Simultaneously published in the United States and Canada. ITS QUALITY AND ACCURACY. Printed in the United States of America. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, The Apple logo is a trademark of SPECIAL, INCIDENTAL, OR Apple Computer, Inc. Use of the CONSEQUENTIAL DAMAGES “keyboard” Apple logo (Option- LIMITED WARRANTY ON MEDIA RESULTING FROM ANY DEFECT OR Shift-K) for commercial purposes AND REPLACEMENT INACCURACY IN THIS MANUAL, without the prior written consent of even if advised of the possibility of such Apple may constitute trademark If you discover physical defects in the damages. infringement and unfair competition manuals distributed with an Apple in violation of federal and state laws. product, Apple will replace the manuals THE WARRANTY AND REMEDIES at no charge to you, provided you return No licenses, express or implied, are SET FORTH ABOVE ARE EXCLUSIVE the item to be replaced with proof of AND IN LIEU OF ALL OTHERS, ORAL granted with respect to any of the purchase to Apple or an authorized technology described in this book. OR WRITTEN, EXPRESS OR IMPLIED. Apple dealer during the 90-day period No Apple dealer, agent, or employee is Apple retains all intellectual after you purchased the software. In property rights associated with the authorized to make any modification, addition, Apple will replace damaged extension, or addition to this warranty. technology described in this book. manuals for as long as the software is This book is intended to assist included in Apple’s Media Exchange Some states do not allow the exclusion application developers to develop program. See your authorized Apple or limitation of implied warranties or applications only for Apple dealer for program coverage and details. liability for incidental or consequential Macintosh computers. In some countries the replacement damages, so the above limitation or Apple Computer, Inc. period may be different; check with exclusion may not apply to you. This 20525 Mariani Avenue your authorized Apple dealer. warranty gives you specific legal rights, Cupertino, CA 95014 and you may also have other rights ALL IMPLIED WARRANTIES ON which vary from state to state. 408-996-1010 THIS MANUAL, INCLUDING Apple, the Apple logo, AppleTalk, IMPLIED WARRANTIES OF HyperCard, HyperTalk, LaserWriter, MERCHANTA- and Macintosh are trademarks of BILITY AND FITNESS FOR A Apple Computer, Inc., registered PARTICULAR PURPOSE, ARE in the United States and other LIMITED IN DURATION TO NINETY countries. (90) DAYS FROM THE DATE OF THE AppleScript, Finder, Geneva ORIGINAL RETAIL PURCHASE OF and System 7 are trademarks of THIS PRODUCT. Apple Computer, Inc. Adobe Illustrator and PostScript are trademarks of Adobe Systems Incorporated, which may be registered in certain jurisdictions. FrameMaker is a registered trademark of Frame Technology Corporation. Contents Figures and Tables xiii Preface About This Guide xv Audience xv Organization of This Guide xvi Sample Applications and Scripts xvii For More Information xviii Getting Started xviii Scripting Additions xviii Other AppleScript Dialects xviii Scriptable Applications xviii Conventions Used in This Guide xix Part 1 Introducing AppleScript 1 Chapter 1 AppleScript, Scripts, and Scriptable Applications 3 What Is AppleScript? 3 What Can You Do With Scripts? 5 Automating Activities 5 Integrating Applications 7 Customizing Applications 7 Who Runs Scripts, and Who Writes Them? 9 Special Features of AppleScript 10 What Applications Are Scriptable? 11 iii Chapter 2 Overview of AppleScript 13 How Does AppleScript Work? 14 Statements 14 Commands and Objects 17 Dictionaries 18 Values 20 Expressions 21 Operations 21 Variables 22 Script Objects 23 Scripting Additions 23 Dialects 24 Other Features and Language Elements 24 Continuation Characters 25 Comments 26 Identifiers 27 Case Sensitivity 28 Abbreviations 29 Compiling Scripts With the Script Editor 30 Part 2 AppleScript Language Reference 31 Chapter 3 Values 33 Using Value Class Definitions 33 Literal Expressions 36 Properties 36 Elements 37 Operators 37 Commands Handled 37 Reference Forms 38 Coercions Supported 38 iv Value Class Definitions 38 Boolean 40 Class 41 Constant 42 Data 43 Date 43 Integer 47 List 48 Number 52 Real 53 Record 54 Reference 57 String 60 Styled Text 64 Text 66 Coercing Values 67 Chapter 4 Commands 71 Types of Commands 71 Application Commands 72 AppleScript Commands 73 Scripting Addition Commands 74 User-Defined Commands 76 Using Command Definitions 77 Syntax 78 Parameters 78 Result 79 Examples 79 Errors 79 Using Parameters 80 Parameters That Specify Locations 80 Coercion of Parameters 81 Raw Data in Parameters 81 Using Results 82 Double Angle Brackets in Results and Scripts 83 v Command Definitions 84 Close 87 Copy 88 Count 92 Data Size 97 Delete 98 Duplicate 99 Exists 99 Get 100 Launch 103 Make 105 Move 106 Open 107 Print 108 Quit 109 Run 110 Save 112 Set 113 Chapter 5 Objects and References 119 Using Object Class Definitions 119 Properties 120 Element Classes 120 Commands Handled 120 Default Value Class Returned 122 References 122 Containers 123 Complete and Partial References 124 Reference Forms 125 Arbitrary Element 126 Every Element 127 Filter 129 ID 130 Index 131 Middle Element 133 vi Name 134 Property 135 Range 136 Relative 139 Using the Filter Reference Form 140 References to Files and Applications 143 References to Files 144 References to Applications 146 References to Local Applications 147 References to Remote Applications 148 Chapter 6 Expressions 149 Results of Expressions 149 Variables 150 Creating Variables 150 Using Variables 152 The “A Reference To” Operator 153 Data Sharing 154 Scope of Variables 155 Predefined Variables 156 Script Properties 156 Defining Script Properties 157 Using Script Properties 157 Scope of Script Properties 158 AppleScript Properties 158 Text Item Delimiters 158 Reference Expressions 160 Operations 161 Operators That Handle Operands of Various Classes 168 Equal, Is Not Equal To 168 Greater Than, Less Than 172 Starts With, Ends With 173 Contains, Is Contained By 175 Concatenation 177 Operator Precedence 178 Date-Time Arithmetic 180 vii Chapter 7 Control Statements 183 Characteristics of Control Statements 184 Tell Statements 185 Tell (Simple Statement) 188 Tell (Compound Statement) 189 If Statements 190 If (Simple Statement) 192 If (Compound Statement) 193 Repeat Statements 194 Repeat (forever) 197 Repeat (number) Times 198 Repeat While 199 Repeat Until 200 Repeat With (loopVariable) From (startValue) To (stopValue) 201 Repeat With (loopVariable) In (list) 202 Exit 204 Try Statements 204 Kinds of Errors 205 How Errors Are Handled 206 Writing a Try Statement 206 Try 207 Signaling Errors in Scripts 210 Error 210 Considering and Ignoring Statements 213 Considering/Ignoring 214 With Timeout Statements 217 With Timeout 218 With Transaction Statements 219 With Transaction 219 Chapter 8 Handlers 221 Using Subroutines 221 Types of Subroutines 223 Scope of Subroutine Calls in Tell Statements 224 Checking the Classes of Subroutine Parameters 225 viii Recursive Subroutines 225 Saving and Loading Libraries of Subroutines 226 Subroutine Definitions and Calls 228 Subroutines With Labeled Parameters 229 Subroutine Definition, Labeled Parameters 229 Subroutine Call, Labeled Parameters 230 Examples of Subroutines With Labeled Parameters 232 Subroutines With Positional Parameters 235 Subroutine Definition, Positional Parameters 235 Subroutine Call, Positional Parameters 236 Examples of Subroutines With Positional Parameters 238 The Return Statement 239 Return 240 Command Handlers 241 Command Handler Definition 241 Command Handlers for Script Applications 243 Run Handlers 243 Open Handlers 246 Handlers for Stay-Open Script Applications 247 Idle Handlers 248 Quit Handlers 249 Interrupting a Script Application’s Handlers 250 Calling a Script Application 251 Scope of Script Variables and Properties 252 Scope of Properties and Variables Declared at the Top Level of a Script 254 Scope of Properties and Variables Declared in a Script Object 258 Scope of Variables Declared in a Handler 263 Chapter 9 Script Objects 265 About Script Objects 265 Defining Script Objects 267 Sending Commands to Script Objects 268 Initializing Script Objects 269 Inheritance and Delegation 271 ix Defining Inheritance 271 How Inheritance Works 272 The Continue Statement 277 Using Continue Statements to Pass Commands to Applications 280 The Parent Property and the Current Application 281 Using the Copy and Set Commands With Script Objects 283 Appendix A The Language at a Glance 289 Commands 289 References