Script Debugger Help - Amazon S3Script Debugger Help > Opening and Saving Scripts > Open > Table of...
Transcript of Script Debugger Help - Amazon S3Script Debugger Help > Opening and Saving Scripts > Open > Table of...
TableofContents
ScriptDebuggerHelp
WelcometoScriptDebugger,fromLateNightSoftware.
ScriptDebuggerisapowerfulenvironmentforeasy,rapiddevelopmentofAppleScriptsolutions.
YoucanuseScriptDebugger7freeforupto20days.Ifyoudonotpurchaseandregisterit,itwillconverttoLitemodewhenyourtrialperiodends.YoucancontinueusingitinLitemodeindefinitelyforfree.IfyoudecidetopurchaseScriptDebugger,youcanregisteritbyenteringyourregistrationnumbertoreactivatefullfunctionality.
InLitemode,somefunctionsaredisabled.MenucommandsthataredisabledinLitemodewillappeardimmedwithaniconnexttothem,asshownhere:
Sometoolbaritemsandothercontrolswillsimplybedimmed.
ThisguidescoversthefullversionofScriptDebugger.FeaturesnotavailableintheLiteversionwillhaveanicontothebeginningofthem,similartothisparagraph.
You’lldiscoverthatScriptDebuggeristhebestwayto:
Explorescriptableapplications.
Examine,navigateandsearchanapplication’sdictionary.
Probearunningapplication’sscriptableobjectsandvalues.
DevelopAppleScriptcode.
ScriptDebuggerhelpsyoueditcodeandinsertboilerplateconstructs.
Runyourcode,examinetheresult,andviewtheAppleeventsthatyouaresendingandreceiving.
Runyourcodealittleatatimetobetterunderstandhowitworks(ortofigureoutwhyitdoesn’t).
AboutThisHelpDocument:
Usethehyperlinks,andthenavigationaidsatthetopandbottomofeachpage,tolearnaboutScriptDebuggerortoreachtheinformationyouneed.
Arrowsandlinksatthebottomleftorrightarefornavigatingbetweenentriesbelongingtothesametopic.Sowhenthere’saFurtherDetails:boxatthebottomofapage,toreadalltheentriesyoucanclickonthefirstandthenusethesearrowsorlinkstomovethroughthemall,ratherthangoingbackandforwardeachtime.
Or,clickthebluearrowintheupperrightcornerrepeatedly,toreadsequentially,likeabook.
ForacompleteTableofContents,clickhere.ATableofContentslinkalsoappearsatthetoprightofeachpage.
Linkswithdoubleunderlinesareexternallinks,sothecontentwillbeopenedinyourdefaultWebbrowser.
Thishelpdocumentissearchable(usingHelpViewer).
FurtherDetails:
OpeningandSavingScriptsExploreDevelopReference
ScriptDebuggerHelp> TableofContents
OpeningandSavingScripts
AscriptisafileconsistingofAppleScriptcode.ScriptsareScriptDebugger’snativedocuments.ReadontolearnhowScriptDebuggeropensandsavesscripts.
LearnhowScriptDebugger:
Opensscripts.WhatfileformatscanScriptDebuggeropen?Whathappensifthere’sdifficultyopeningafile?
Savesscripts.WhatformatsdoesScriptDebuggersavein?WhatadditionalinformationdoesScriptDebuggersave?
Also,ScriptDebuggergivesyouaccesstosecondaryinformationaboutascriptfile.Learnabout:
Description.Ascript’sdescriptioncanserveasaremindertothedeveloper,anexplanationtousers,andasplashscreeninanapplet.
Manifest.ScriptDebuggercreatesasummaryofwhatexternalitiesarerequiredinorderforyourscripttobeeditedandexecuted.
Bundlecontents.Ifascriptisinabundleformat,youcaneditthebundle’ssettingsandcontents.
FurtherDetails:
OpenSaveDescriptionManifestBundle
Explore
ScriptDebuggerHelp>OpeningandSavingScripts> TableofContents
Open
Here’showtoopenafilewithScriptDebugger.Theresultofopeningascriptfileiseitherascriptwindoworatabwithinascriptwindow.
NewScriptWindow
Tomakeanewscriptwindow,chooseFile>NewScriptor,ifyou’dliketosummonthetemplatechooser,chooseFile>NewScriptFromTemplate.
WhathappenswhenyouchooseFile>NewScriptdependsonyoursettingsinScriptDebugger’sGeneralpreferences,under“ForNewDocuments”:
Ifyou’veselected“ShowTemplateChooser”,thetemplatechooserappears.Fromhere,youcanselectthekindofscriptyouwanttocreate.InmostcasesthiswillbeAppleScript>AppleScript(foranormalcompiledscriptfile)orApplications>Applet(foranapplet).
Ifyou’veselected“Usetemplate”,thekindofscriptyou’vespecifiedasthedefaultiscreated,withoutdisplayingthetemplatechooser.Tospecifyakindofscriptasthedefault,clicktheChooseTemplatebuttonintheGeneralpreferencespaneandusethetemplatechoosertospecifyatemplate.InmostcasesthiswillbeAppleScript>AppleScript.
(Evenifyou’veselected“Usetemplate”,youcanstillsummonthetemplatechooseratanytimebychoosingFile>NewScriptFromTemplate.)
(Also,therearevariouswaysthatyoucanmakeanewscripttargetingaparticularapplication.)
Here’showtosetthesizeandviewconfigurationthatanewscriptwindowwilladopt.
NewScriptTab
Tomakeanewscripttabwithinthefrontmostscriptwindow,chooseFile>NewScriptTabor,ifyou’dliketosummonthetemplatechooser,chooseFile>NewScriptTabFromTemplate.
Alternatively,ifthewindowalreadyhasatab,pressthe“plus”buttontotherightofthelasttab.
WhathappenswhenyouchooseFile>NewScriptTab(orpressthe“plus”button)dependsonyoursettingsinScriptDebugger’sGeneralpreferences,under“ForNewDocuments”,inexactlythesamewayasforFile>NewScript.Seethediscussionearlieronthispage.
ClickheretolearnallabouttabsinaScriptDebuggerscriptwindow.
OpenExistingScript
Toopenanexistingscript,doanyofthefollowing:
NavigatetothefileinthestandardOpenFiledialog,usingFile>Open.
Searchforthefilebynameorcontents,usingFile>OpenQuickly.
Ifyou’verecentlyhadthisscriptopen,chooseitfromFile>OpenRecent.
Drag-and-dropthescriptfileontoScriptDebugger’siconintheFinderortheDock.
IfScriptDebuggeristheownerofscriptfiletypes,double-clickthescriptfileintheFinder.(Butthatdoesn’tworkforanapplet,sincebydefaultwhenanappletisopenedfromtheFinder,itruns.)
Thereisalsoaspecialwayofquicklyopeningalibraryscriptreferredtoinyourcode:
Selectwithinalinereferringtothescript(suchasusescript"MyScript");then,chooseFile>OpenScriptLibrary“MyScript”.
(Ifthelibraryscripthasadictionary,adialogappears,offeringyouachoiceofwhethertoopenthescriptoritsdictionary.)
WhetheranexistingscriptopensasaseparatewindoworasatabwithinthefrontmostwindowdependsonaGeneralpreference;underOpeningDocuments,checkoruncheck“OpeninTabs”.Toreverseyoursettingonaparticularoccasion,holdtheShiftkeyasyouopenascript.
AGeneralpreferenceletsyoutellScriptDebuggertowarnyouifopeninganexistingscriptmightcauseanapplicationtolaunch.
LearnwhatfilesScriptDebuggercanopen.
LearnhowScriptDebuggercanhelpwhenthere’stroubleopeningafile.
FurtherDetails:
TheTemplateChooserTabsCompatibilityOpeningaCompiledScriptasText
Save
ScriptDebuggerHelp>OpeningandSavingScripts>Open> TableofContents
TheTemplateChooser
Thetemplatechooserletsyouopenanewscriptfromastoredscriptfileinaspecialtemplateformat.Thetemplateactsasthebasisforyourworkinanewuntitledscript.Whenyoueditandsavethenewuntitledscript,you’llsaveitunderanewnameandinanewlocation.
Thetemplatescriptsdisplayedbythetemplatechooserfallintocategories:
ScriptTemplates.ThesearetemplatefilesprovidedbyScriptDebuggeritself.Theyare:
AppleScript>AppleScript.AcompiledscriptfilewithusestatementsfortheAppleScriptversionandscriptingadditions.Optionsletyouspecifyascriptbundle,insertacommentblockgivingauthoranddateinformation,andtoggleonoroffpersistentproperties.
AppleScript>AppleScriptObjC.Likethepreceding,withausestatementfortheFoundationframework.
AppleScript>EmptyAppleScript.Anemptyscript,withnousestatementsandnooptions.
Application>Applet.AtraditionalAppleScriptappletwithusestatementssimilartotheAppleScript>AppleScripttemplate,containingarunhandler.Optionsletyouspecifyadroplet(anappletthatacceptsdrag-and-dropoffilesandfolders),insertacommentblockgivingauthoranddateinformation,andtoggleonoroffpersistentproperties.
Application>AppletUsingAppleScriptObjC.Likethepreceding,withausestatementfortheFoundationframework.
Application>EnhancedApplet.TheEnhancedAppletusesanappletshellwithextrafunctionality.TheseappletsareafeatureofthefullversionofScriptDebugger,andarenotavailableinLitemode.
Plug-inScripts.Compiledscriptfilesalreadycontainingcode,structuredforusebyaparticularapplicationorsituation:
ContactsPluginScript.AscripttobetriggeredinContactsthroughamenuitemthatwillappearinthemenuthatpopsupwhenyouclickonacategoryname(e.g.“work”infrontofanemailorphonenumber).SeetheAddressBookRolloverSuiteintheContactsdictionary.
DigitalHubScript.AscripttobetriggeredwhenaCDorDVDismounted.SeeDigitalHubActionsintheScriptingAdditionsdictionary.
FolderActionsScript.Ascripttobetriggeredwhenaneventoccursinacertainfolder,suchasafilebeingaddedtoit.SeeFolderActionsintheScriptingAdditionsdictionary.
MailRuleScript.AscripttobetriggeredinMailaccordingtoauser-definedrule.SeetheperformmailactioncommandintheMaildictionary.
UserTemplates.Templatesthatyoucreate.Tomakeatemplate:
1. Configureascriptthewayyouwantit.
2. ChooseFile>SaveasTemplate.
3. Saveinto~/Library/ApplicationSupport/ScriptDebugger7/Templates(theSavedialogwilldisplaythisfolderasyourdestinationautomatically).ScriptDebuggerconvertsyourscriptintoaspecialtemplateformat.
Atemplatethatyoucreate(oranytemplate,actually)includesthecontentofthescriptthatyousaveasatemplate.Thisincludessuchfeaturesas:
Textofthescript
Description
Expressions
Butitdoesnotincludethesizeorviewstateofthescriptwindow.Thosearewindowfeatures,nottemplatefeatures,andcomefromyournewscriptwindowappearancedefaults.
Thecontentofatemplatethatyoucreate(oranytemplate)canincludeclippingexpansiontags.
Youcanorganizeyourusertemplatesintocategories.Todoso,organizethemintofolderswithintheTemplatesfolder.AfolderintheTemplatesfolderwillappearasacategoryintheleftcolumnofthetemplatechooser.
Tabs
ScriptDebuggerHelp>OpeningandSavingScripts>Open> TableofContents
Tabs
Ascriptwindowcancontainmultipletabs.Eachtabisaseparatedocument.
Thus,adocumentcanappeareitherinawindowbyitselforasatabinawindowalongwithotherdocuments.Usewhicheverarrangementyoufindconvenientfornavigationandorganizationasyouwork;mixandmatch.
Whetheradocumentappearsinaseparatewindoworasatabinascriptwindowalongwithotherdocumentsdependsonhowyouopenit.
Ifyoupreferyourscriptwindowsalwaystohavetabs,evenwhenthere’sonlyone,chooseView>ShowTabBaratatimewhenthere’sonlyonetab.
Tonavigatebetweentabswithinawindow,chooseWindow>SelectNextTaborWindow>SelectPreviousTab.
Torearrangetabswithinawindow,dragatabsideways.
Toturnatabintoaseparatewindow,dragthetabrightoutofitscurrentwindow.
(Alternatively,youcanopenatabasaseparatewindowwithoutdestroyingthetab:chooseFile>OpeninNewWindow.Theresultisadocumentthat’sbeingeditedbymultiplewindowssimultaneously.)
Tomoveadocumentintoatabinagivenwindow,dragitstabtothetabbaroftheintendedwindow.
Tocloseatab,chooseFile>CloseTab,orclickthesymbol(“x”ordotinacircle)attheleftofthetab.
Tocloseallbutonetab,holdOptionandclickthesymbol(“x”ordotinacircle)attheleftofthetab.
Tocloseawindowandallitstabs,chooseFile>CloseWindow,orclickthereddotatthetopleftofthewindow.
TomergeallwindowsintoasinglewindowchooseWindow>MergeAllWindows.
TheTemplateChooser Compatibility
ScriptDebuggerHelp>OpeningandSavingScripts>Open> TableofContents
Compatibility
ScriptDebuggercanopenanyofAppleScript’snativefiletypes:
Compiledscriptfilewiththebytecodeinthedatafork.ThisisthestandardmodernformatcreatedbythecurrentversionofApple’sScriptEditor.
Scriptbundle.Thecompiledscriptfile(withthebytecodeinthedatafork)isinsidethebundle,whichhasafileextensionof.scptd.
Appletbundle.ThisisthestandardAppleappletformat.
EnhancedAppletbundle.ThisisascriptthatusesScriptDebugger’sEnhancedappletshell.Althoughtheycanbeopenedinanymode,theycannotbesavedinLitemode.
ScriptDebuggercansaveinanyoftheaboveformatsaswell.However,EnhancedappletscanonlybesavedfromthefullversionofScriptDebugger;inLitemodetheymustbesavedinoneoftheotherformats.
ScriptDebuggercanalsoopenafileinanyoftheolderhistoricalscriptformats.Itdoesn’tsaveintheseolderformats,sotosavesuchafile,you’llneedtoselectoneofthemodernformats.Theolderformatsinclude:
Compiledscriptfilewiththebytecodeintheresourcefork.Thisistheoldestformat,goingbackasfarasAppleScriptitself.
Nonbundleapplet.ScriptDebuggercanopennonbundleappletscreatedonanysystem,includinga“Classicapplet”(MacOS9andearlier).
ScriptDebuggercanalsoopenatextfile.ThefileisassumedtobeUTF-8unlessthereisaBOM(byteordermark)indicatingotherwise;ifthere’sanencodingerror,thefileisassumedtobeintheoldMacRomanencoding.LineendingscanbeMacorUnix.
Tabs OpeningaCompiledScriptasText
ScriptDebuggerHelp>OpeningandSavingScripts>Open> TableofContents
OpeningaCompiledScriptasText
Sometimes,AppleScriptpreventsScriptDebuggerfromopeningacompiledscriptfile,orshowsthefile’scontentswithrawAppleeventcodes.Thisindicatesthatsomethinghasgonewrongwiththedecompilationprocess.Forexample,anapplicationorscriptingadditionneededbythescriptismissing,orascript’sinternalaliastoanapplicationhasbroken.
IfthescriptwasoriginallysavedwithScriptDebugger,youcanopenthescriptastext.Todoso:
ChooseFile>RecoverDamagedScript.
ThisfeatureworksbecausewhenScriptDebuggersavesacompiledscript,itsavesnotonlythecompiledbytecodebutalsotheuncompiledtext.Theuncompiledtextisplacedinthefile’sresourcefork(or,ifthefileisabundle,inafilewithinthebundle).
Warning:Ifyoueditascriptwithsomeotherscripteditorapplication,thestoreduncompiledtextmaynolongermatchthecurrentstateofthebytecode.
OpenAsTextInsteadofLaunchinganApplication
ScriptDebuggermayautomaticallyletyouopenascriptastext,ifyouattempttoopenacompiledscriptthattargetsanapplicationwhichmustbelaunchedinorderforAppleScripttodecompileit.
Forexample,supposeScriptEditorisnotrunningandyouopenacompiledscriptthattargetsScriptEditor.IfScriptEditorisn’talreadyrunning,AppleScriptwantstolaunchitinordertodisplaythescript.ScriptDebuggerdetectsthisandcanoptionallyintervene:
IfyourchoiceinScriptDebugger’sGeneralpreferencesis“Warnwhenapplicationsmaybelaunched,”ScriptDebuggerpresentsthisdialog:
Youcanproceedtoopenthescript(andallowScriptEditortolaunch)ifyouwish,butperhapstheoverheadoflaunchinganapplicationjusttoreadascriptseemsunwarranted.IfthisscriptwassavedwithScriptDebugger,itcontainsatextversion,andyoucanclickOpenAsTexttoopenthatinstead.ThusyoucanreadthescriptwithoutlaunchingScriptEditor.(ButtocompilethescriptyouwillhavetoletAppleScriptlaunchScriptEditor.)
Ifthescriptdoesnotcontainatextversion,theOpenAsTextbuttonwillnotbepresent.
IfyourchoiceinScriptDebugger’sGeneralpreferencesis“Alwaysopenastextwithoutlaunchingapplications,”then,ifthescriptcanbeopenedastext,ScriptDebuggerwillopenitastext,withoutbotheringtodisplaythedialog.
Compatibility
ScriptDebuggerHelp>OpeningandSavingScripts> TableofContents
Save
TosaveascriptwithScriptDebugger:
ChooseFile>Save.
ChooseFile>SaveAs.Thiscreatesanewfileor,ifyouwish,overwritestheoriginalfile.
ChooseFile>SaveACopyAs.Thiscreatesanewfilebutthescriptwindowcontinuestoshowtheoriginalfile.
Scriptscanbesavedinvariousformats.Ifyouarecreatinganewfile,optionsforspecifyingthedesiredformatappearintheSavedialog(theFormatpop-upmenu).Alternatively,youcanspecifyformatoptionsbychoosingfromthesehierarchicalmenus:
File>ScriptFormat
File>ApplicationOptions(ifit’sanapplet)
File>CodeSigning(ifit’sanapplet)
Tosaveascript,thescriptmustbecompiled.Ifyouwishtosaveascriptwithoutcompilingyoucansaveitastext.
Acompiledscript(orapplication)canalsobeexportedasarun-onlyscript.
FurtherDetails:
FormatsRun-OnlyScriptWhatIsSavedFileOwnerSpotlightandQuickLook
Open Description
ScriptDebuggerHelp>OpeningandSavingScripts>Save> TableofContents
Formats
ScriptDebuggercansavescriptsinfourbasicforms:asacompiledscriptfile,asatraditionalAppleapplet(application),asanEnhancedApplet,orastext.
EnhancedappletsareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Ineachcase,youhavevariousoptionsabouttheresultingformatandotherdetails.
Acompiledscript(orapplication)canalsobeexportedasarun-onlyscript.
FurtherDetails:
CompiledScriptApplication(Apple)Application(Enhanced)Text
Run-OnlyScript
ScriptDebuggerHelp>OpeningandSavingScripts>Save>Formats> TableofContents
CompiledScript
ScriptDebuggercansavecompiledscriptfilesintwoformats.YoucanchooseaformateitherfromtheFile>ScriptFormathierarchicalmenuorintheSavedialog.
CompiledScript.Afilewiththecompiledbytecodeinthedatafork.ThisisthedefaultformatcreatedbythecurrentversionofApple’sScriptEditor.ItisbackwardscompatibletoallversionsofmacOSandtoverylateversionsofAppleScriptinMacOS9.
CompiledScriptBundle.Abundle(package)withthebytecodeasadataforkcompiledscriptfileinsidethebundle.Ithastheadvantagethatyoucanstoreancillaryfilesinsidethebundle.
Usethebundleinspectortoconfigurebundlesettingsandtomanipulatethecontentsofthebundle’sResourcesfolder.
HistoricalNote:Theoldestcompiledscriptformatisafilewiththecompiledbytecodeintheresourcefork.ScriptDebuggercanopenascriptfileinthisformat,butitwillsavewiththebytecodeinthedatafork.
Warning:Acompiledscriptsavedindebugmodewillnotrunnormallyinotherenvironments(andwillnotevenopeninApple’sScriptEditor).Unlessthat’swhatyouintend,besuretosavethescriptinnormalmodewhenyou’refinisheddebuggingit.
Foraplaincompiledscriptfile,ScriptDebuggerstoressomesecondaryinformationinthefile’sresourcefork.Inabundleformatfile,however,noresourceforksareused;secondaryinformationissavedinseparatefiles.(Thedescriptionissavedinan.rtfdfile,therecoverytextissavedinan.rtffile,andtheothersecondaryinformationissavedina.plistfile.)Forthisreason,abundleformatfileisthemostcompatiblewithversioncontrolsystems,non-Macfilesystems,andsoon.
Application(Apple)
ScriptDebuggerHelp>OpeningandSavingScripts>Save>Formats> TableofContents
Application(Apple)
Acompiledscriptcanbesavedasanapplication,traditionallyknownasanapplet.Anappletisastand-aloneapplication.WhenopenedintheFinder,thescriptruns.
ScriptDebugger7supportstwotypesofapplet:traditionalApplescriptapplets,andEnhancedapplets.EnhancedAppletssupportthefeaturesoftraditionalappletsdescribedbelow.
EnhancedappletsareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.YoucanopenanexistingenhancedappletinLitemode,butyouwillonlybeabletosaveitasastandardAppleapplet.
Atraditionalapplet’sscriptcanbeeditedinScriptDebuggerbyopeningitinanyoftheusualways.
YoucansaveascriptasanappletandleavethescriptopeninScriptDebugger.ThisallowsyoutotestthescriptfromtheFinderandtheneasilyedititinScriptDebugger.
Tip:ScriptDebuggerhassomefurtherfeaturesforhelpingyoutestascriptthatisdestinedtobesavedasanapplet.Youcantestindividualhandlersintheapplet,andyoucandebugtheappletwhileitisrunning.
Tosaveascriptasanapplication(ifitisn’tanapplicationalready):
ChooseFile>SaveAsandselectApplication(Apple)orApplication(Enhanced)fromtheFormatpop-upmenu.
Anappletisalwayssavedasabundle;thishastheadvantagethatyoucanstoreancillaryfilesinsidethebundle.
Besidestheformat,youcanalsosetfurtheroptionsforthebehavioroftheresultingapplication.Todoso,usethecheckboxesintheSavedialog,orchoosefromthehierarchicalFile>ApplicationOptionsmenu.(YoucanalsoaddStayOpenandShowStartupbuttonstothescriptwindow’stoolbar.)
ShowStartupScreen.Thescript’sdescriptionisusedasa“splashscreen”whentheappletstartsup.Thissplashscreenalsocontainsbuttonsallowingtheusertoquitorruntheapplet.
StayOpen:
Anappletthatdoesnotstayopenrunsitsscriptwhenopenedandthenautomaticallyquits.
Anappletthatdoesstayopendoesnotautomaticallyquitafterrunningitsscript(theusercanchooseitsQuitmenuitemtoquititlater).Thisisusefulif,forexample,theappletrunsahandlerperiodicallyatidletime.
CodeSigning.Ifanappletistobedistributedtootherusers,andifyouhaveamembershipintheAppleDeveloperProgram,youmightwishtocodesigntheapplet.
Usethebundleinspectortoconfigurebundlesettingsandtomanipulatethecontentsofthebundle’sResourcesfolder.
Warning:Anapplicationsavedindebugmodewillnotrunnormally(whenlaunched,itwillinitiateanexternaldebuggingsessioninScriptDebugger).Unlessthat’swhatyouintend,besuretosavetheapplicationinnormalmodewhenyou’refinisheddebuggingit.
CompiledScript Application(Enhanced)
ScriptDebuggerHelp>OpeningandSavingScripts>Save>Formats> TableofContents
Text
Youcansaveascriptastext,withoutcompiling.Theresultisanordinarytextfile(inUTF-8encoding).
Todoso,doeitherofthefollowing:
ChooseFile>Save,File>SaveAs,orFile>SaveACopyAs,andchooseTextfromtheFormatpop-upmenuintheSavedialog.
ChooseFile>ScriptFormat>Text.
Youmayneedtosaveascriptwithoutcompilingforavarietyofreasons:
Youwanttosaveyourwork,butthescriptdoesn’tcompile(andyoudon’thavetimetofigureoutwhyrightnow).
Youwanttostorethescriptinaformthat’sguaranteedtobereadableonanothercomputer.(Acompiledscriptfilemightfailtoopenonanothercomputerforavarietyofreasons.)
NOTE:Ifyouattempttosaveascriptandthere’sacompileerror,ScriptDebuggerwilloffer,intheCompileErrordialog,tosavethescriptastext.
Ifyouwish,youcanspecifylineendingsforatextfile.Todoso,usetheTextLineEndingspop-upmenuintheFile>SaveAsdialog.Ingeneralyoushouldnothavetodothis.IfyouleavethelineendingssettingatAsIs(thedefault),lineendingswillbeleftalone.Anyothersettingwillforcelineendingstobesetatsomespecificvalue,andthiscanalterthefunctionalityofyourscript(asexplainedhere).(Toviewlineendingsastheyarenowinyourscript,youcanshowinvisibles.)
Application(Enhanced)
ScriptDebuggerHelp>OpeningandSavingScripts>Save> TableofContents
Run-OnlyScript
Arun-onlyscriptcontainsthescript’scompiledbytecodebutdoesnotcontainthefurtherinformationneededtodecompileanddisplayit.Arun-onlyscriptistypicallyusedasawayofdistributingascriptsothatotheruserscanrunthescriptbutcannotviewormodifythescript’ssourcecode.
Tosaveascriptasrun-only:
ChooseFile>ExportRun-OnlyScript.(YoucanalsoaddanExportRun-Onlybuttontothescriptwindow’stoolbar.)
TheresultingSavedialogcontainsthesameformatoptionsasforanordinarycompiledscriptorapplication.
Ifyouareexportingacompiledbundleorapplicationandyouwishtocodesignthebundle,youcanrestrictsigningtoexportsonlybycheckingExportonlyinthebundleinspector.
Thesavedialogalsocontainsacheckbox,“Makebundledscripts&librariesrun-only”.Thisisusefulincaseswhereyou’veaddedextrascriptstoascriptbundleorapplicationbundle.Ifyoudon’tcheckit,thebundle’smainscriptwillbesavedasrun-only,buttheextrascriptsinthebundlewillnotbe.
Arun-onlyscriptcannotbereadoreditedeveragain,evenbyyou,itscreator.ThisiswhyScriptDebuggerimplementsthisfeatureasaformofexport.Afterexportingasrun-only,youroriginalscriptisunaffected(andthereforeremainseditable).Ifyouedityouroriginalscriptandyouwishtopropagatethechangestotherun-onlyversionofthescript,exportitagain.
ScriptDebuggerwillpreventyoufromoverwritinganyopendocumentswhenyouexportrun-only.
Formats WhatIsSaved
ScriptDebuggerHelp>OpeningandSavingScripts>Save> TableofContents
WhatIsSaved
ScriptDebuggersavesthefollowinginformationintoacompiledscriptfile:
Thecompiledscriptbytecode.
Thescript’sdescription,ifany.
Persistentinformationsuchasthecurrentvaluesofscriptproperties,ifthescriptisconfiguredtodothis.
Scriptwindowstate(suchasitssizeandposition)andviewsettings,plus:
Whatpanes(suchastheresultpane)areshowingandhowtheyareconfigured.
Eventlogpaneandwindowconfiguration.
Expressions.
Breakpoints,ifthescriptissavedindebugmode.
Foraplaincompiledscriptfile,ScriptDebuggerstoressomesecondaryinformationinthefile’sresourcefork.Inabundleformatfile,however,noresourceforksareused;secondaryinformationissavedinseparatefiles.(Thedescriptionissavedinan.rtfdfile,therecoverytextissavedinan.rtffile,andtheothersecondaryinformationissavedina.plistfile.)Forthisreason,abundleformatfileisthemostcompatiblewithversioncontrolsystems,non-Macfilesystems,andsoon.
Run-OnlyScript FileOwner
ScriptDebuggerHelp>OpeningandSavingScripts>Save> TableofContents
FileOwner
WhenafileisopenedfromtheFinder,itisopenedbytheapplicationthatownsit.Therefore,becauseapplicationsotherthanScriptDebugger(suchasApple’sScriptEditor)canclaimownershipofscriptfiles,youmightwanttocontroltheownershipoffilescreatedbyScriptDebugger.
TomakeScriptDebuggertheownerofscriptfiles:
GototheGeneralpreferencepaneandcheck“DefaulteditorforOSAscripts,appletsanddroplets.”
ThisisaquickwayofsettingScriptDebuggerastheownerforfileswiththerelevantfilenameextensions(.scptforacompiledscriptfile,.scptdforacompiledscriptbundle,.applescriptforascripttextfile);youcoulddothesamethinginascriptfile’sGetInfodialogintheFinder.
WhatIsSaved SpotlightandQuickLook
ScriptDebuggerHelp>OpeningandSavingScripts>Save> TableofContents
SpotlightandQuickLook
ScriptDebuggersupportsbothSpotlightandQuickLookaccesstosavedcompiledscriptfiles.
Spotlight
SpotlightisthemacOSindexingtechnology.Itkeepstrackoffilesandtheircontentsandallowsyoutosearchrapidlyforafilebasedonitsnameoritscontents.Ifyoucanrememberawordortwousedinyourfile,youcanfinditquickly,ratherthanhavingtorememberwhatfolderit’sin.
ScriptDebuggercontainsaSpotlightimporterforcompiledscriptfiles.ThismeansthatifScriptDebuggerispresentonyourcomputer,AppleScriptcompiledscriptsaresearchablewithSpotlight.Youcansearchforascriptfilebynameorcontents(includingitsdescription).
ScriptDebuggerprovidesdirectaccesstosearchforafileandopenitusingSpotlightinitsfullversion:
ChooseFile>OpenQuickly.Inthedialog,typesomewordsorletterstosearchfor;thesearchincludesthefile’sname,contents,anddescription.Matchingscriptfilesarelisted,alongwiththeirpathname.
Topreviewthecontentsofaselectedfileorfiles,clicktheQuickLookbutton(orpressSpacebar).SeethediscussionofQuickLooklateronthispage.
Toopenafileorfiles,double-clickthefilelisting(orselect,andthenclicktheOpenbuttonorpressReturn).
QuickLook
QuickLookisthemacOStechnologyforviewingapreviewofthecontentsofafilewithouttheoverheadofopeningthatfileintheapplicationthatownsit.Forexample,youcanQuickLookafiledirectlyintheFinder.
ScriptDebuggercontainsaQuickLookgeneratorforcompiledscriptfilesandapplets.ThismeansthatthesystemisprovidedwiththeinformationitneedstotranslateyourfileintoapreviewthatQuickLookcanpresent.IfascripthasbeensavedwithScriptDebugger,itwillbeviewablewithQuickLookalongwithitsAppleScriptcompiledscripttextformatting;otherwise,itwillappearinQuickLookasplaintext.
Becauseyou’rejust“peeking”atthescript’stextwithQuickLook,thereisnoneoftheoverheadinvolvedwithactuallyopeningthescript:thereisnodecompilationandthereforethereisnoneedtolaunchanytargetedapplications.
FileOwner
ScriptDebuggerHelp>OpeningandSavingScripts> TableofContents
Description
Ascriptcanhaveadescription.Thiscanserveasaremindertothedeveloper,anexplanationtousers,andasasplashscreeninanapplet.Youcanpastestyledtextintothispane.
Toaccessascript’sdescription:
ChooseView>ResourcesTab.
Or,clickthesecondShowbuttoninthescriptwindowtoolbar.
Thedescriptionappearsinthetoppaneattherightsideofthescriptwindow.Youcanpastestyledtexthere,andthestylingwillbemaintainedinanapplet’ssplashscreen.
Save Manifest
ScriptDebuggerHelp>OpeningandSavingScripts> TableofContents
Manifest
ScriptDebuggercangenerateamanifestforyourscript—alistofitsexternaldependencies.
Thiscanbeusefulpurelyasinformation.Itcanalsohavepracticalimplications.Forexample,supposeyouintendtomovethescripttoanothermachineorsendittoanotheruser.Ifthescriptrequiresascriptableapplication,thescriptwon’trunonamachinethatlacksthatapplication.Thankstothemanifest,you’llbeforewarnedaboutsuchdependencies.
ManifestsareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Toseeascript’sdependenciesintheManifestdialog:
ChooseFile>ShowManifest.(YoucanalsoaddaManifestbuttontothescriptwindow’stoolbar.)
Thescript’sdependenciesarelistedbycategory:
ApplicationDependencies.Theseareapplicationsspecifiedinausestatementoratellortermsblock.
ScriptLibraryDependencies.Thesearelibraryscriptsspecifiedinausestatement.
ScriptingAdditionDependencies.Thesearescriptingadditionswhosetermsareusedinthescript.[Technicalnote:Rarely,ascriptingadditionmayprovidecoercionsinadditiontoterminology;ScriptDebuggercannotdetectthese.]
FrameworkDependencies.Theseareframeworksspecifiedinausestatement.
Buttonsallowyoutorevealaselectedapplication,libraryscript,scriptingaddition,orframeworkintheFinder.
Youcanalsoviewthedictionaryforaselectedapplication,libraryscript(ifithasadictionary),orscriptingaddition.
ByscriptingScriptDebuggeryoucanretrievethesevaluesviaadocument’susedapplications,usedscriptlibraries,usedscriptingadditions,andusedframeworksproperties.
Description Bundle
ScriptDebuggerHelp>OpeningandSavingScripts> TableofContents
Bundle
Ifascript’sformatisacompiledscriptbundleoranapplicationbundle,youcanworkwiththebundlesettingsandcontentsusingthebundleinspector.
Toworkwithbundlesettingsandcontents:
ChooseView>ResourcesTab.
Or,clickthesecondShowbuttoninthescriptwindowtoolbar.
Ifthescriptisinabundleformat,thebundleinspectorappearsattherightofthescriptwindow.
Thebundleinspectorisdividedintothreesections.
Description
Astyledtextdescriptionofthebundle.Inthecaseofabundle,youareactuallyeditingthetextofResources/description.rtfdinsidethebundle.Youcanpastestyledtextintothispane.
Settings
ThesesettingsactuallyeditthecontentsoftheInfo.plistfileinsidethebundle.
YoucanalsoreadmoreaboutthebundlesettingsinthisposttotheScriptDebuggeronlineforum.
BundleIDAuniqueidentifierforthebundle.Thisisimportantparticularlyifthebundleisanapplet;everyapplicationshouldhaveauniqueidentifier.Byconvention,theidentifierstartswithcom.andisstructuredlikeareverseURLhostname.Bydefault,ScriptDebuggerwillcombinetheBundleIDPrefixfromyourGeneralpreferenceswiththenameofthebundle.
CopyrightThecopyrightstringappearsintheFinder’sGetInfowindowforthisfile.Bydefault,ScriptDebuggerderivesthecopyrightstringforanappletfromtheCopyrightNoticefromyourGeneralpreferences.
VersionTheversionstringappearsintheFinder’sGetInfowindowforthisfile,andisthevaluereturnedforanappletorbundle-formatscriptlibrary’sversionproperty.Itusuallyconsistsofeitheranintegervalue,ortwoorthreenumbersseparatedbystops—
forexample,1.0.
Build#Avalue,usuallyanumber,entirelyforyouruse.CheckIncrementonsaveifyouwouldlikeScriptDebuggertoincrementthisnumbereachtimethescriptissaved.
ScriptingDef.Thismenulistsanysdeffilesinthebundle’sResourcesfolder.YoucanuseansdeffiletodefineAppleScriptterminologyforyourscript,thusgivingyourscriptadictionary.Thisisusefulparticularlyifthisisalibraryscripttobeusedbyothers,whocanconsultthescript’sdictionarytolearnhowtouseyourscript.
AppletIconThismenulistsanyicns,oricon,filesfoundinthebundle’sResourcesfolder.Bydefault,scriptapplicationscontainingopenhandlerscontainaniconfilenamedroplet.icns,otherwisetheycontainonecalledapplet.icns.Togiveanappletacustomicon,createasuitableiconfilenamedsomethingotherthanappletordroplet,anddragitintotheresourcesareatoaddittotheapplet’sbundle.YouwillthenbeabletochooseitintheAppletIconmenu.Whenyouaddacustomicon,youdonotneedtoremovetheexistingstandardiconfiles—whenyoueditandsaveafiletheymaybere-createdanyway.
CodeSigningThismenuletsyouchoosewhethertocodesignthebundleaftersaving,andifsowhichsignaturetouse.ScriptDebuggerwilllisttheavailablesignatures,andassumingyouhaveavalidAppledeveloperIDyouwillnormallyuseonethatbeginswith“DeveloperIDApplication:”.ThiswillenableyourscriptstopassscrutinybyGateKeeperwhenyousendthemtootherusers.TheExportonlyoptionconfinescodesigningtorun-onlyversionscreatedusingtheExportRunOnlyScript...command.Becausecodesigningcantakesometime,especiallywhenascriptcontainsextraresources,thismakesitsimpletosignonlyversionsyouintendtodistribute.
MinimumOSThisentryletsyoudefinetheminimumversionanappletwillrununder.ThiscanbeusefulifyourappletrequiresparticularfeaturesunavailableundersomeversionsofmacOS.IfyouarewritingAppleScriptObjCcode,theearlierofthevaluehereandthevaluerepresentedbyanyuseAppleScriptversion...statementintheapplet’sscriptwillbeusedtofilterterminologyprovidedincode-completion:ScriptDebuggerwilltrynottoofferyouAppleScriptObjCtermsthatrequirealaterversionthanyourspecifiedminimum.EnhancedAppletsmusthaveaMinimumOSof10.10orlater.
ATS:AllowarbitraryloadsATSstandsforAppTransportSecurity,whichisawayApplerestrictsanapplicationfrommakingunsecureWebconnections.BycheckingAllowarbitraryloads,youwillturnoffAppTransportSecurityfortheapplet.YoumaywanttodothisifyouareusingAppleScriptObjCandloadingnon-httpssites.AppTransportSecuritysupportsfinercontrolthanasimpleonoroff,butdoingthatrequireseditingthebundle'sInfo.plistfiledirectly.Ifyouopenascriptthathasbeencustomizedinthisway,thecheckboxwillappearinanindeterminatestate,andyouwillonlybeabletoturnAppTransportSecurityfullyonoroff.
Applet:BackgroundonlyThisoptioncanconfigureanappletsothatitdoesnotappearintheDockormenubar.Thiscanbeusefulforcertaintypesofstay-openapplets.
Export:IncludeusedlibrariesThisoptionisforusersdeployingscriptscontainingembeddedscriptlibraries.Whenthisoptionischecked,youcandevelopyourscriptsusingscriptlibrariesstoredinyour~/Libraries/ScriptLibrariesfolder.Thenwhenyouexportarun-onlydeploymentversion,anyusedlibraryscriptswillbecopiedintotheexportedbundle.
OverrideDropletBehaviorInthissectionyoucanmodifyhowanappletcontaininganopenhandlerbehaveswhenfilesaredraggedoveritsicon.Therearetwofields,whichareemptybydefault.Inthisstatedropletsbehaveasalways,allowingyoutodrag-and-dropanytypeoffileorfolder.
TheAcceptfileswiththeseextensionsfieldiswhereyoucanenterextensions,siginifyingthatfileswiththoseextensionscanbedroppedontheapplication.Youcanentermultiplevalues;typeaspaceorcommatostartanewextension.Donotincludethe.character;ScriptDebuggerwillnotletyouenterit.
TheAcceptitemsconformingtotheseUTIsfieldiswhereyoucanenteroneormoreUniformTypeIdentifiers,siginifyingthatfilesthatconformtoanyoftheentriescanbedroppedontheapplication.EnteringUTIscanbedoneinthreeways.Youcantypethemindirectly,similarlytoextensions,youcandragafileorfilesofthetypeyouwantoverthefield,oryoucanusetheAdd...popupmenuabovethefieldtoentersomeofthecommonsystem-declaredUTIs,suchaspublic.folder.
Youcanseehowthisworksinthisshortvideo.
Resources
TheResourcespanedisplaysthecontentsoftheResourcesfolderinsidethebundle.
Toaddanexistingfileorfoldertothebundle:
ClickthePlusbuttonatthebottomofthebundleinspector.
Or,chooseAddExistingFilesfromthecontextualmenu.
Or,drag-and-dropanitemfromtheFinderintothebundleinspector.
Todeleteaselectedfileorfolderinthebundle:
ClicktheMinusbuttonatthebottomofthebundleinspector.
Or,chooseDeletefromthecontextualmenu.
Torenameaselectedfileorfolderinthebundle:
PressReturntoedititsname.
Or,chooseRenamefromthecontextualmenu.
Torevealaselectedfileorfolderinthebundle:
ChooseFile>RevealXXXinFinder.
Or,chooseRevealXXXinFinderfromthecontextualmenu.
Tocreateanewfolderinthebundle:
ChooseNewFolderfromthecontextualmenu.
TocreateaScriptLibrariesfolderinthebundle:
ChooseAddScriptsLibrariesFolderfromthecontextualmenu.
Toopenanonscriptfileinthebundle:
Double-clickthefileinthebundleinspector.
Manifest
ScriptDebuggerHelp> TableofContents
Explore
ThebiggestchallengefortheAppleScriptprogrammerisfiguringoutwhattosaytoascriptableapplication.ScriptDebuggergivesyoupowerfultoolsforexploringascriptableapplicationsothatyoucanquicklywritesuccessfulscriptstargetingit.
Youcanexploreanapplication’sdictionary.ScriptDebuggerhelpsyounavigateandsearchthedictionary,andletsyouviewdictionaryinformationfullyandclearly.
Youcanexploreascriptableapplication’sobjects.Forexample:
Ifascriptableapplicationisrunning,youcanexploreitsentirecurrentsetofobjectsinrealtime.
Whiletheapplicationisrunning,youcanseethenamesandvaluesoftheattributes(elementsandproperties)thatitactuallyhasatthatmoment—andifthoseattributesareobjects,youcanseetheirattributes,andsoforth.Youcancopyareferencetoanattributeintoyourscript.
Youcanevenchangeapropertyvalueorcollection,withoutwritingascript.Youcanseehowthisworksinthisdemonstrationvideo.
Ifascriptableapplicationreturnsanobjectvalueastheresultofascriptoralineofcode,youcanexplorethatresult.
FurtherDetails:
DictionaryExplorer
OpeningandSavingScripts Develop
ScriptDebuggerHelp>Explore> TableofContents
Dictionary
OneofScriptDebugger’smosthelpfulfeaturesisitsdisplayofthedictionaryofascriptableapplication,scriptingaddition,orscriptlibrarythatdefinesterminology.
Inadictionarywindow,ScriptDebuggermakesitveryeasyforyou:
Toopenthedictionaryofascriptableapplication,scriptingaddition,orscriptlibrarythatdefinesterminology.
Tonavigatethedictionary.
Toviewtheinformationinthedictionaryinavarietyofways.
Toexploreascriptableapplication’sobjectsinrealtime.
FurtherDetails:
OpenDictionaryWindowDictionaryWindowApplicationExplorer
Explorer
ScriptDebuggerHelp>Explore>Dictionary> TableofContents
OpenDictionaryWindow
Youcanopenanapplication’sdictionarywindowinseveraldifferentways,dependingonwhatyou’redoingandwhat’sconvenient.Themostcommonwayis:
ChoosefromtheFile>OpenDictionarymenu.
Andtherearemanyotherways:
Ifanapplicationisrunning,youcanopenitsdictionarywindowdirectly.
Ifyou’reworkinginanapplication,youcanchooseOpenXXXDictionary(where“XXX”isthefrontmostapplication)fromScriptDebugger’sDockmenu.
Ifyou’vealreadyworkedwithanapplication,ScriptDebuggerremembersthisfact,andyoucanopenthedictionarywindowfromalistofpreviouslyusedapplications.
Ifyou’reeditingascriptthattargetsanapplication,youcanopenthatapplication’sdictionarywindowdirectly.
Ifyou’reeditingascriptthattargetsalibraryscriptwithadictionary,youcanopenthatscript’sdictionarywindowdirectly.
Ifthedictionaryyouwanttoopenisascriptingadditiondictionary,youcanopenitsdictionarywindowdirectly.
Therearevariousgeneralwaystoopenanyapplicationorscriptingaddition’sdictionarywindow.
Also,youcanswitchtothefrontmostdictionarywindowatanytime(e.g.,whileworkinginascriptwindow)bychoosingWindow>Dictionary.Ifthereisnoopendictionarywindow,anemptydictionarywindowiscreated.
Here’showtoopenmultipledictionarywindows.
Insomecases,openinganapplication’sdictionarywillrequiretheapplicationtoberunning.Ifthisisthecase,andtheapplicationisnotrunning,thenwhenyouasktoopentheapplication’sdictionary,ScriptDebuggerwilllaunchtheapplication,whichmaycauseadelay.However,onceScriptDebuggerhasopenedanapplication’sdictionary,itcachesthedictionary(providedyouhavenotunchecked“Cachegenerateddictionaries”intheDictionarypreferences).Thus,havingopenedsuchanapplication’sdictionary,youcannowclosetheapplicationanditsdictionaryandlateropenitsdictionaryagainandthistimeScriptDebuggerwillnothavetolaunchtheapplication.
NOTE:Ifyoutargetscriptableapplicationswithaplug-inarchitecture,suchasQuarkXPressorInDesign,readthediscussiononthispageaboutregeneratingthedictionarycache.
FurtherDetails:
RunningApplicationsRecentandFavoriteApplicationsCurrentContextScriptingAdditionsOpenAnyDictionaryWindowOpenMultipleDictionaryWindowsDictionariesInspector
DictionaryWindow
ScriptDebuggerHelp>Explore>Dictionary>OpenDictionaryWindow> TableofContents
RunningApplications
Ifanapplicationisrunningrightnow,youcanquicklyopenitsdictionarywindow.
ChooseFile>OpenDictionary.Intheresultinghierarchicalmenu,you’llseealistheadedRunning.Chooseanapplicationfromthemenutoopenanapplication’sdictionarywindow.
Inanyopendictionarywindow,locatetheapplicationinthedictionarieslistattheleftsideofthewindow,underRunning.Clickthenameoftheapplication.
Inthedictionariesinspector,locatetheapplicationunderRunning.Double-clickitsname,orselectitsnameandclickDictionary,orselectitsnameandchooseOpenXXXDictionaryfromthecontextualmenu.
Ifwhatyouwanttoopenisthedictionaryofthefrontmostapplication,useScriptDebugger’sDockmenu.Thiscontainsanitem,OpenXXXDictionary,where“XXX”isthefrontmostapplication.Chooseit,andScriptDebuggerwillcometothefrontwiththatapplication’sdictionarywindowopen.
RecentandFavoriteApplications
ScriptDebuggerHelp>Explore>Dictionary>OpenDictionaryWindow> TableofContents
RecentandFavoriteApplications
WhenyouaskScriptDebuggertoworkwithanapplicationorscriptlibrarythatincludesscriptingterminology,ScriptDebuggerremembersthisfactandputstheapplicationorlibraryinitsdictionarieslist.Youcanopenarecentlyusedapplicationorscriptlibrary’sdictionarywindowquickly:
ChooseFile>OpenDictionary.Intheresultinghierarchicalmenu,you’llseealistheadedRecent.Chooseanapplicationorscriptlibraryfromthemenutoopenthatitem’sdictionarywindow.
Inanyopendictionarywindow,locatetheapplicationorlibraryinthedictionarieslistattheleftsideofthewindow,underRecent.Clickthenameoftheapplication.
Inthedictionariesinspector,locatetheapplicationorlibraryunderRecent.Double-clickitsname,orselectitsnameandclickDictionary,orselectitsnameandchooseOpenXXXDictionaryfromthecontextualmenu.
Ifyoufrequentlyuseanapplicationorscriptlibrarythatincludesscriptingterminology,youcandesignateitafavoriteapplication.Todoso:
Inanyopendictionarywindow,orinthedictionariesinspector,selecttheapplicationorlibraryandchooseFavoritefromthecontextualmenusothatitischecked.
(Ifyouchangeyourmindlaterandwantanapplicationorlibrarynolongertobedesignatedafavoriteapplication,selectitandchooseFavoritefromthecontextualmenusothatitisunchecked).
Toopenafavoriteapplicationorscriptlibrary’sdictionaryquickly:
ChooseFile>OpenDictionary.Intheresultinghierarchicalmenu,you’llseealistheadedFavorites.Chooseanapplicationorlibraryfromthemenu.
Inanyopendictionarywindow,locatetheapplicationorlibraryinthedictionarieslistattheleftsideofthewindow,underFavorites.Clickthenameoftheapplicationorlibrary.
Inthedictionariesinspector,locatetheapplicationorlibraryunderFavorites.Double-clickitsname,orselectitsnameandclickDictionary,orselectitsnameandchooseOpenXXXDictionaryfromthecontextualmenu.
RunningApplications CurrentContext
ScriptDebuggerHelp>Explore>Dictionary>OpenDictionaryWindow> TableofContents
CurrentContext
Ifyou’reeditingascriptthatcontainsatellblocktargetinganapplication,youcanquicklyopenthatapplication’sdictionarywindow.
Selectanywhereinsidethetellblocktargetingtheapplicationwhosedictionaryyouwanttoopen.(Thisistoputyourselectionintothedesiredtellcontext.)ThenchooseFile>OpenXXXDictionary,where“XXX”willbethenameoftheapplication.(Thecommand-keyshortcut,Command-Dbydefault,willcomeinveryhandyhere,andwillrapidlybecomesecondnature.)
Alternatively,chooseOpenXXXDictionaryfromthecontextualmenu.
Ifyou’reeditingascriptthattargetsalibraryscriptwithadictionary,youcanquicklyopenthatscript’sdictionarywindow.
Selectinalinecontainingtheexpressionscript"XXX",where“XXX”isthelibraryscript’sname.ThenchooseFile>OpenScriptLibrary“XXX”.Adialogappears,lettingyouopenthescript’sdictionaryorthescriptitself.(Again,thedefaultkeyboardshortcutisCommand-D.)
RecentandFavoriteApplications ScriptingAdditions
ScriptDebuggerHelp>Explore>Dictionary>OpenDictionaryWindow> TableofContents
ScriptingAdditions
ThedictionarywindowforanyinstalledscriptingadditionscanbeopeneddirectlyinScriptDebugger.
ChooseFile>OpenDictionary.Intheresultinghierarchicalmenu,you’llseealistheadedAppleScript.ChooseScriptingAdditions.
Inanyopendictionarywindow,locateScriptingAdditionsundertheAppleScriptheadinginthedictionarieslistattheleft.Clickit.
Inthedictionariesinspector,locateScriptingAdditionsundertheAppleScriptheading.Double-clickit,orselectitandclickDictionary,orselectitandchooseOpen“ScriptingAdditions”Dictionaryfromthecontextualmenu.
CurrentContext OpenAnyDictionaryWindow
ScriptDebuggerHelp>Explore>Dictionary>OpenDictionaryWindow> TableofContents
OpenAnyDictionaryWindow
Ifanapplicationisnotrunningandyouhaven’tworkedwithitrecently,andifyouarenotcurrentlytargetingitinascript,youcanopenitsdictionarywindowinthefollowingways:
Inanyopendictionarywindow,locatetheapplicationinthedictionarieslistontheleftsideofthewindowunderAll,andclickit.
Inthedictionariesinspector,locatetheapplicationunderAll.Double-clickitsname,orselectitsnameandclickDictionary,orselectitsnameandchooseOpenXXXDictionaryfromthecontextualmenu.
ChooseFile>Open.Thisbringsupadialogwhereyoucanchooseanything.Ifwhatyouchooseisanapplicationorscriptingaddition,itsdictionarywillopen.Ifwhatyouchooseisalibraryscriptwithadictionary,adialogwillappearaskingwhetheryouwanttoopenthescript’sdictionaryorthescriptitself.
ChooseFile>OpenDictionary>Application.Thisbringsupadialogwhereyoucanchooseanapplication,scriptingaddition,orlibraryscriptwithadictionary,toopenitsdictionary.
LocatetheapplicationorscriptingadditionintheFinderanddrag-and-dropitsiconontoScriptDebugger’siconintheFinderortheDock.
LocatetheapplicationorscriptingadditionintheFinderanddrag-and-dropitsiconontoaScriptDebuggerscriptwindow.ScriptDebuggerwillputupadialogaskingwhatyouwanttodo.Oneoftheoptionsistoopentheapplication’sdictionarywindow.
NOTE:ScriptDebuggercanalsoopenansdeffiledirectly,andwillpresentitsdictionarywindowasifyouhadopenedascriptableapplication.Thisisintendedasanaidifyou’redevelopingoreditingansdef.
ScriptingAdditions OpenMultipleDictionaryWindows
ScriptDebuggerHelp>Explore>Dictionary>OpenDictionaryWindow> TableofContents
OpenMultipleDictionaryWindows
Whenyouopenadictionarywindow,itnormallyreusesthefrontmostdictionarywindowifthereisone,andyoucanswitchamongapplications(anddictionaries)withinthatdictionarywindow.However,youcanalsoopenmultipledictionarywindows,inordertoseedictionaryinformationfortwodifferentapplicationssimultaneously,orworkwithanapplicationintwosimultaneousmodes(forexample,adictionaryandanexplorer),andsoon.Todoso:
Bringadictionarywindowtothefront,andchooseFile>OpenXXXDictionaryinNewWindow(whereXXXistheapplicationcurrentlybeingviewedinthisdictionarywindow).
Or,inadictionarywindow,Control-clickanapplication’snameinthedictionarieslistandchooseOpenXXXDictionaryinNewWindow.
Or,holdtheShiftkeyandchooseWindow>NewDictionaryWindow.
Or,holdOptionwhileopeningadictionarywindow.Forexample,holdOptionwhilechoosingFile>OpenDictionary.Or,holdOptionwhilepressingtheDictionarybuttoninascriptwindow’sdictionariesinspectorortellcontextinspector.
OpenAnyDictionaryWindow DictionariesInspector
ScriptDebuggerHelp>Explore>Dictionary>OpenDictionaryWindow> TableofContents
DictionariesInspector
ThedictionariesinspectorlistsapplicationsthatScriptDebuggerhas“met”invariousways—thedictionarieslist.Thislistappearsinseveralplacesintheinterface—forexample,inadictionarywindow,andinshortenedform(withouttheAllcategory)intheFile>OpenDictionarymenuandtheEdit>PasteTellmenu.
ThedictionariesinspectorisintheInspectorstabofascriptwindow.Toseethedictionariesinspector:
ChooseView>InspectorsTab.
Or,clickthethirdShowbuttoninthescriptwindowtoolbar.
Toopenanapplication’sdictionary:
SelectitandclicktheDictionarybutton.
Or,selectitandchooseFile>OpenXXXDictionary.
Or,Control-clickitandchooseOpenXXXDictionaryfromthecontextualmenu.
Or,double-clicktheapplication’sname.
Or,clickanapplication’striangletoopenit,revealingcommandsforthatapplication:
Selectacommand.Thedictionaryinfoforthatcommandisshowndirectly,inthedictionariesinspector.
Selectacommand,andopenthedictionaryinanyoftheprecedingways.Thedictionarywindowopens,withthatcommandselectedintheterminologylist.
HoldOptiontoopenthedictionaryinanewdictionarywindow.
Toinsertatellblocktargetinganapplication:
SelectitandclickthePasteTellbutton.
Or,selectitandchooseDictionary>PasteTellXXX.
Or,Control-clickitandchoosePasteTellXXXfromthecontextualmenu.
Or,clickanapplication’striangletoopenit,revealingcommandsforthatapplication.Selectacommand,andPasteTellinanyoftheaboveways.Atellblockcontainingatemplateforthatcommandispasted.
HoldOptiontopasteintoinanewscriptwindow.
Alternatively,drag-and-dropthenameofanapplicationfromthedictionariesinspectorintoascriptwindow.
Toinsertausingtermsfromblocktargetinganapplication:
SelectitandclickthePasteUsingbutton.
Or,Control-clickitandchoosePasteUsingTermsFromXXXfromthecontextualmenu.
HoldOptiontopasteintoinanewscriptwindow.
Tolearnanapplication’slocation:
Hoverthemouseovertheapplication’sname,toseethetooltip.
ToshowanapplicationintheFinder:
SelectitandchooseFile>RevealXXXinFinder.
Or,Control-clickitandchooseRevealXXXinFinderfromthecontextualmenu.
Tobringanapplicationtothefront:
SelectitandchooseDictionary>ActivateXXX.
Or,Control-clickitandchooseActivateXXXfromthecontextualmenu.
Toquitarunningapplication:
SelectitandchooseDictionary>QuitXXX.
Or,Control-clickitandchooseQuitXXXfromthecontextualmenu.
Youcanalsosearchdictionariesfromthedictionariesinspector.
YoumaybecuriousabouthowtheAllsectionofthedictionarieslistisautomaticallypopulated.Basically,anapplicationisaddedtothelistautomaticallyinthefollowingcircumstances:
WhenScriptDebuggerislaunched.ScriptDebuggersearchesyourcomputerforscriptableapplications,andaddsthemtothelistiftheyhaveeverrun.(Adictionarypreference,“OnlysearchApplicationsfolderfordictionaries”,allowsyoutolimitthescopeofthissearch.)
Whenanapplication’sdictionaryisexplicitlyopened.
Whenanobjectspecifierisexplored(so,forexample,whenyoutargetanapplicationinascriptanditreturnsanobjectasthescript’sresult).
Whenatellblocktargetingthatapplicationisdetectedinyourcode.
Runningascripttargetinganapplicationmightnotaddthatapplicationautomaticallytothelist.ThereasonisthatAppleScriptandScriptDebuggeraretwodifferententities,soAppleScriptcanrunascriptwithoutScriptDebuggerseeingandanalyzingthecontentsofthatscript.
OpenMultipleDictionaryWindows
ScriptDebuggerHelp>Explore>Dictionary> TableofContents
DictionaryWindow
MeetScriptDebugger’sdictionarydisplay.
Herearethepartsofthedictionarywindow:
1. Thetoolbar.
2. Thedictionarieslist.Thisisthesamelistthatappearsinthedictionariesinspector,andinshortenedform(withouttheAllcategory)intheFile>OpenDictionarymenuandtheEdit>PasteTellmenu.Toworkwithanapplication’sdictionaryorexplorerstartinginanexistingdictionarywindow:
Clicktheapplication’snameinthedictionarieslist.
Control-clicktheapplication’snameandchooseOpenXXXDictionaryinNewWindowtocreateaseparatedictionarywindow.
Toshoworhidethedictionarieslist:
ChooseDictionary>ShowDictionariesList.
Ifyouhidethedictionarieslist(tosavescreenrealestate,perhaps),youmightliketocustomizethedictionarywindow’stoolbartoaddtheDictionariesbutton,whichsummonsapop-upmenucontainingtheentiredictionarieslist.
Theapplicationnamesinthedictionarieslistaredraggable.Drag-and-droponeintoascriptwindow.TheresultisthesameasdraggingtheapplicationfromtheFinderintothescript.
3. Theterminologylist.It’salistofallterminologyinthecurrentdictionary.Selectintheterminologylisttoseethecorrespondingdictionaryentryintheinfopane.
Theterminologylistisreplacedwithsearchresultswhenyousearchthedictionary.
Theterminologylistisreplacedwithanobjectmodeldiagramwhenyoudisplaytheobjectmodel.
Theterminologylistisremovedcompletelywhenyoudisplaytheexplorer.
4. Theinfopane.Itdisplaysanentryorentriesfromthedictionary.Todeterminewhatentryisdisplayedhere,selectintheterminologylist(orintheresultsofasearch).
Theinfopanemaybereplacedwiththeexplorer.
Thedictionarywindowmayappearinanyofthreemodes,accordingtoyourchoiceintheDictionarymenu(oryoucanusetheViewbuttonsinthetoolbar):
Dictionary>ShowDictionary(ortheDictionarybutton):Displaysthedictionarieslist(unlessyou’vehiddenit),theterminologylist(ortheresultsofasearch),andtheinfopane.
Dictionary>ShowObjectModel(ortheObjectModelbutton):Displaysthedictionarieslist(unlessyou’vehiddenit),theobjectmodeldiagram,andtheinfopane.
Dictionary>ShowExplorer(ortheExplorerbutton):Displaysthedictionarieslist(unlessyou’vehiddenit)andtheapplicationexplorer.
TheObjectModelandExplorerviewsarefeaturesofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Whichmodethedictionarywindowisinwhenitfirstappearsorwhenyouswitchtoanotherapplication’sdictionarydependsonyourchoiceintheDictionarypreferences:
ShowDictionary;ShowObjectModel;ShowExplorer:Thedictionarywindowswitchesautomaticallytothatmode.
Rememberstate:Thedictionarywindowswitchestothemodeitwaslastinforthatapplication.
Youcansavethecurrentdictionarywindow’sconfiguration(suchasitssize)asthedefaultforfuturenewdictionarywindows.Todoso:
ChooseWindow>SetDefaultDictionaryWindowSize&State.
ChooseWindow>ResetDefaultDictionaryWindowSize&Statetoreverttothebuilt-indefaults.
NOTE:Thescriptingadditionsdictionarycanappearonlyinthefirstmode,Dictionary.There’snoobjectmodelorexplorerforscriptingadditions,becauseascriptingadditionisnotanapplicationsoithasnoobjectstodiagramorexplore.
Here’showtoopenmultipledictionarywindows.
FurtherDetails:
TerminologyListDictionaryInfoPaneHierarchiesandDiagramsSearchinDictionaryLookUpDefinitionBackandForwardMiscellaneousDictionaryActions
OpenDictionaryWindow ApplicationExplorer
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow> TableofContents
TerminologyList
Theterminologylistattheleftofthedictionarywindowistheprimarywayofnavigatinganapplication’sdictionary.ChooseDictionary>ShowDictionary(orclickDictionaryinthedictionarywindow’stoolbar).
Selectintheterminologylisttodisplaythecorrespondingdictionaryentryintheinfopane.
Toselectanddisplayinfoformorethanoneterminthelist,Shift-clicktoselectarangeofentries,orCommand-clicktoselectmultipleindividualentries.
Ifyouselectacategoryname,infoisdisplayedforalltermsinthatcategory.Forexample,ifyouselectClasses,it’sasifyou’dselectedalltheindividualnamesofclasses—infoisdisplayedforalltheclassesinthedictionary.
Youcanusearrowkeystonavigatetheterminologylist,thoughitisprobablymorecommontousethemouse.
Anothercommontechniqueistosearchtheterminology,thusfilteringtheterminologylisttoconsistonlyoftermsthatresultfromthesearch.
NOTE:Thetermsintheterminologylistaredraggable.Drag-and-dropatermintoascriptwindow.TheresultissimilartoPasteTell.
Hereisadiscussionofthevariouscategoriesandiconsyou’llseedisplayedintheterminologylist(andinsearchresults).
FurtherDetails:
TypesofEntitiesShownintheTerminologyList
DictionaryInfoPane
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow>TerminologyList> TableofContents
TypesofEntitiesShownintheTerminologyList
Thisisalistofthevarioustypesofentitiesshownintheterminologylistinthedictionarywindow,aswellasinresultsfromsearchinginthedictionarywindowandthedictionariesinspector.
SuiteAsuite( )isanartificialgroupingofentitiescreatedbythedeveloperoftheapplication’sscriptingmodel.Asuitecancontainanyothertypeofentity(exceptanothersuite),andinmostdictionaries,everydictionaryentryispartofsomesuite.Theterminologylistdisplaysallsuchtermstwice—firstwithintheirsuites,andthenbycategory.
CommandAcommandisaverb,somethingthatyoutellanapplicationoroneofitsobjectstodo.Theicondistinguishesbetweenafunction( ),whichreturnsaresult,andaplaincommand( ),whichdoesnot.Commandparametersaremarkedinasearchresultby .
EventAnevent( )isamessagesentbyanapplicationtoyourcode.Yourcodecanreceivethismessagethroughaneventhandler.Forexample,FolderActionsareimplementedthroughevents;seetheFolderActionssuiteintheScriptingAdditionsdictionary.
Dictionariesdonotalwaysdistinguisheventsfromcommands,soScriptDebuggermaysometimesclassifyeventsascommands.
ClassAclass( )isadatatype.Aclasscanhaveattributes—properties( )andelements(whicharethemselvesdenominatedasclasses).Mostofwhatyoudoinscriptinganapplicationinvolvesworkingwithpropertiesandelements.Yougetandsetthevaluesofproperties,andyoumanipulateelementsinvariousways(askingforparticularelementsorlistsofelements,creatingnewelements,deletingelements,andsoforth).
RecordArecord( )isasortoflightweightclass,typicallyusedonlyincommunicatingdatabetweenanapplicationandyourscript.ScriptDebuggerdistinguishesrecordsfromclassesonlywhenthetargetapplicationhasansdef-baseddictionary(becauseonlyansdef-baseddictionarycandrawsuchadistinction).
EnumerationAnenumeration( )isadatatypewhosevalueisalwaysoneofapredefinedlistofconstants( ).Forexample,insomedictionariestheclosecommandhasasavingparameterwhosevalueisamemberofthesaveoptionsenumeration:eithertheconstantyesortheconstantnoortheconstantask.Anenumeration’sconstantsarecalleditsenumerators.EnumerationssometimeshavenoEnglishname,sointhatcaseScriptDebuggernamesthembytheirrawAppleeventcode.
Inthedictionaryinfopane,eachenumerationislisted,withitsenumerators,onapageofitsown.Avaluetypeisshownasahyperlinkwiththeenumerationname.Clickthislinktoseetheenumeration’sownpage,listingitsenumeratorvalues.Forexample,thesavingparameteroftheclosecommandmightbelistedasthesaveoptionsenumeration;toseetheactualvaluesyou’reallowedtosupplyforthisparameter,you’dclicksaveoptionstoseethesaveoptionsenumerationonitsownpage,wheretheenumeratorsyes,no,andaskarelisted.
TypeAtype( )isabuilt-inAppleScriptdatatype,suchasbooleanortext.ItisnotalwaysobviouswhatthedistinctionisbetweenaTypeandaClass.Insomecontexts,thedifferenceisthataClasscanhaveattributes(propertiesandelements),butsomedictionariesfailtodrawthisdistinctionconsistently.
ScriptingAdditionThiscategoryappearsonlyatthestartoftheScriptingAdditionsterminologylist.ScriptDebuggercollectsthedictionariesofallinstalledscriptingadditionsintoasingledictionary,butthiscategoryletsyoubrowseanindividualscriptingaddition.Ascriptingadditioncategorylistsbothsuitesandcategories,justasattoplevel,sointheScriptingAdditionsterminologylist,acommand(say)mightbeshownfourtimes:insideitsscriptingadditionunderitssuite,insideitsscriptingadditionunderitscategory(Commands),attoplevelunderitssuite,andattoplevelunderitscategory(Commands).
Individualscriptingadditionsaremarkedastotheirlocation,namelytheScriptingAdditionsfolderintheLibraryatthesystem( ),computer( ),user( ),ornetwork( )level.
SummaryofSymbols
#inafolder Enumeration
#inacircle Constant(Enumerator)
Cinacircle Class
Cinahexagon Command
Einahexagon Event
FinahexagonFunction(Commandwithresult)
Pinasquare Parameter
Prinasquare Property
Rinacircle Record
Sinafolder Suite
Tinacircle Type
!inatriangle PowerPC-only*
OSX-styleX System**
iMacdisplay Computer**
Personsilhouette User**
Networkglobe Network**
*ThePowerPC-onlyiconappearswhenScriptDebuggerisrunningnativelyonanIntel-basedmachineandascriptingadditionisPowerPConly.ItalertsyoutothefactthatIntel-nativeAppleScriptenvironments,includingScriptDebugger,willnotloadthisscriptingaddition.(ButaCarbonapplet,oranyapplicationthatexecutesAppleScriptscriptsandisnotauniversalbinaryandthereforerunsunderRosetta,willloadsuchascriptingaddition.)
**ScriptingAdditioniconsreflectthelocationoftheLibrary/ScriptingAdditionsfoldercontainingthemarkedscriptingadditionfile:/System,toplevel,theuser’shomefolder,orthenetwork,respectively.
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow> TableofContents
DictionaryInfoPane
Theinfopaneofthedictionarywindowdisplaysthedictionaryentryforoneormoretermsselectedintheterminologylistortheobjectmodeldiagram.ScriptDebugger’sdisplayofdictionaryentrieshastheseusefulfeatures:
Completeness.ScriptDebuggerdisplaysalltheinformationinadictionary,whereotherscripteditorapplicationsmayomitsomeinformation.
Hyperlinking.EverythinginbluewithadottedunderlineinaScriptDebuggerdictionaryisalink.Youclickthislinktofollowit.Forexample,inthefirstillustrationbelow,everytimethepersonclassismentioned,it’salinkwhichyoucanclicktojumptothedictionary’sentryonthepersonclass.Ifyou’reindoubtaboutwhatanylinkedwordmeans,clickonit.(There’snopenaltyfordoingso,asyoucanalwayscomebackafterwards.)
Note:linkswithsolidunderlinesareexternal(i.e.somewhereontheInternet)andwillbedisplayedinyourwebbrowser.
Cross-Referencing.ScriptDebuggeranalyzesthedictionaryanddisplaystheresultinginformationascross-references.Forexample,atthebottomofthefirstillustrationbelow,ScriptDebuggertellsyouwhatclassescanbetheobjectofthepaircommand.Inthesecondillustrationbelow,showingthealiasentryfromBBEdit’sdictionary,ScriptDebuggertellsyoueverycommandthattakesanaliasasaparameter,andeveryclassthathasapropertythat’sanalias.Everycross-referenceisahyperlink.
ExtraInformation.ScriptDebuggeroptionallyprovidesextrainformationaboutbuilt-inAppleScripttypes.Forexample,inthesecondillustrationbelow,aliasisabuilt-inAppleScripttype.TheDescriptionsectionisextrainformation,comingnotfromthedictionaryoftheapplication(BBEdit)butfromScriptDebuggeritself.ThisextrainformationisinstructionalandcanbeespeciallyhelpfultoAppleScriptbeginners.
TheaboveillustrationshowsthetypicalfeaturesofacommandasdisplayedinScriptDebugger.Thecommand’ssyntaxisdemonstratedbyatemplate(“FunctionSyntax”),whichyoucaninsertintoyourscript.Theresultandparametersareclearlyshown.Classes(person)andtypes(boolean)arehyperlinks.Classesthatcanbetheobjectofthiscommandarecross-referencedandhyperlinked.
TheaboveillustrationshowsthetypicalfeaturesofaclassasdisplayedinScriptDebugger.Theclass’spropertiesareclearlylisted.Types(file,text)arehyperlinks.Commandswherethisclassisaparameter,andclasseswherethisclassisapropertyorelement,arecross-referencedandhyperlinked.Thisparticularclassisabuilt-inAppleScripttype,soextrainformationaboutthetypeisprovidedintheDescriptionsection.
TheFindcommand(Search>Find)workswithintheinfopane,andcanbeausefulwaytolocatedesiredinformationquickly.
Youcantweakseveralaspectsoftheinfopanedisplay:
Youcanchangethesizeofthetext.
Youcansetwhetheraclass’sinformationshouldincludepropertiesandelementsinheritedfromitssuperclass.
Youcansetwhethertodisplayextradocumentationsuppliedbydictionaryauthors,aswellasLateNightSoftware’sownexplanationsofAppleScript’sbuilt-inclasses.
YoucansetwhethertorevealtherawAppleeventcodesfordictionaryterms.
Thesesettingsapplytothedictionarydisplayforoneapplicationatatime,andtheyarepersistent(thatis,theyarerememberedthenexttimeyouopenthedictionarywindowforthatparticularapplication).
FurtherDetails:
SizeInheritanceExtraDocumentationAppleEventCodes
TerminologyList HierarchiesandDiagrams
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow>DictionaryInfoPane> TableofContents
Size
Youcanchangethesizeofthetextinthedictionarywindow’sinfopane.Todoso:
ChooseDictionary>LargerTextorDictionary>SmallerText,possiblyseveraltimesuntilyougetasuitabletextsize.(YoucanalsoaddaTextSizebuttontothedictionarywindow’stoolbar.)
Inheritance
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow>DictionaryInfoPane> TableofContents
Inheritance
ScriptDebugger’sdictionarydisplaycanflattenthedisplayofinheritedattributesinthedictionarywindow’sinfopane.
So,forexample,ifinheritedattributesaredisplayed,thentheinfofortheFinder’sfolderclassshowsyoutheinfoforthecontainerclass(becausefolderinheritsfromcontainer)andtheitemclassaswell(becausecontainerinheritsfromitem).Infact,thefolderclasshasnoattributesofitsown;allitspropertiesareinheritedfromitem,andallitselementsareinheritedfromcontainer.
Toflattenthedisplayofinheritedattributes:
ChooseDictionary>ShowInheritedDefinitions.Ifthismenuitemischecked,thedisplayofinheritedattributesisbeingflattened.
Thereisadifferentsortofdictionaryflattening,whichScriptDebuggerperformsautomatically.Insomedictionaries,anentryisrepeatedmultipletimes.Forexample,theinformationabouttheapplicationclassmightbedistributedovertwoentries,eachinadifferentsuite.(So,forexample,inTextEdit’sdictionary,someapplicationclassinformationisintheStandardSuite,someofitisintheTextEditSuite.)Inthiscase,ScriptDebuggerwilldisplaytheentryinitsmultiplelocations,butinbothplacesitcombinestheinformationfrombothentries.Thus,nomatterwhichinstanceoftheentryyoulookat,youwillseealltheinformationaboutthatentry.
Size ExtraDocumentation
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow>DictionaryInfoPane> TableofContents
ExtraDocumentation
Besidesamerecomment,scriptingdictionaryauthorscanincludemultipleformattedparagraphsofexplanation.
Youcantogglethedisplayofextendedexplanatorymaterialinthedictionarywindow’sinfopane.Todoso:
ChooseDictionary>ShowExtraDocumentation.Ifthemenuitemischecked,theextendedexplanatorymaterialisbeingdisplayed.
ScriptDebuggeritselfalsoprovidessomesupplementarydictionaryinformationthatis“injected”intothedictionarydisplay,suchastheDescriptionofthealiasdatatypeshownhere.ThissupplementaryinformationisinstructionalandcanbeespeciallyhelpfultoAppleScriptbeginners.
Inheritance AppleEventCodes
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow>DictionaryInfoPane> TableofContents
AppleEventCodes
InplaceoftheEnglish-liketerminologyinthedictionarywindow’sinfopane,ScriptDebuggercandisplaytherawAppleeventcodestowhichtheycorrespond.ThiscanbeusefulwhenyouwanttoanalyzearawAppleevent(asdisplayedintheeventlogpane,forinstance),orwhenyouneedtotrackdownaterminologyclash.
TotogglethevisibilityofrawAppleeventcodes:
ChooseView>ShowRaw(Chevron)Syntax.Ifthemenuitemischecked,Appleeventcodesareshowing.
Or,clicktheRawSyntaxbuttoninthedictionarywindow’stoolbarsothatitishighlighted(whiteicononblackbackground).Thebuttonisoptional;ifyoudon’tseeit,youcanadditbycustomizingthetoolbar.
YoucanalsoseerawAppleeventcodesinscripts,inanoutliner,andintheeventlogwindow.
ExtraDocumentation
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow> TableofContents
HierarchiesandDiagrams
ScriptDebuggercanportraytheclassesinadictionaryasarrangedintwohierarchies—thecontainmenthierarchyandtheinheritancehierarchy.ChooseDictionary>ShowObjectModel(orclickObjectModelinthedictionarywindow’stoolbar).
ObjectmodeldisplayisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Totogglebetweenthetwohierarchies,chooseDictionary>ShowContainment(orclickContains)orDictionary>ShowInheritance(orclickInherits).
Thecontainmenthierarchyreflectsthefactthatanobjecthasattributes(propertiesandelements),andanattributecanbeanotherobject.Thus,intheory,itshouldbepossibletostartatthe“top”ofthehierarchy(whichisusuallythesingleinstanceoftheapplicationclass)anddescribetherelationshipsbetweenclassesasatree.Thistreeissometimesreferredtoastheapplication’sobjectmodel.Thecontainmenthierarchyexpressesa“has-a”relationshipamongclasses.
Theinheritancehierarchyisanartificeoriginallyintroducedasawayofmakingdictionariessmaller.Forexample,intheFinder,folderanddiskaretwodifferentclasses,buttheyhavemanypropertiesandelementsincommon.Forinstance,theybothhaveanentirecontentspropertysayingwhat’sinthem,andtheycanbothhavefolderelementsandfileelementsreflectingthehierarchyofitemsondisk.Thusitsavesspace,andmakesconceptualsenseaswell,toencapsulatetheseandallotherattributessharedbyfoldersanddisks,andtoexpressthemasaseparateclass(herecalledcontainer).Thefolderclassandthediskclassarethensaidtoinheritfromthecontainerclass,sothattheysharethesepropertiesandelementsbyvirtueofthisinheritance.Theinheritancehierarchyexpressesan“is-a”relationshipamongclasses.
ScriptDebugger’sdictionarydisplaycanflattenthedisplayofinheritedattributesintheinfopane.Clickheretoreadmoreaboutthisfeature.
Theaboveillustration(showingSafari’scontainmenthierarchy)istypicalofwhatyou’llseeintheobjectmodeldiagram.
Herearesomecluesabouthowtheobjectmodeldiagramworks:
Clickanyterminthediagramtoseetheinformationforthattermdisplayedintheinfopane.Thus,thediagramisanadditionalwaytonavigatethedictionary.
Note:There’snoseparatedictionaryentryforapropertyname,sowhenyouselectapropertynameinthediagram,theinfopaneshowstheinfoforthatproperty’sclass—andthatclassisalsoautomaticallyselectedinthediagram.
Clickthe+or-buttonattherightendofanyclass’sname,toexpandorcollapsethehierarchyshowninthediagramfromthatpoint.
Inthecontainmenthierarchy,tick-marksindicateaone-to-onerelationship(aproperty)oraone-to-manyrelationship(anelement).
Inthecontainmenthierarchy,double-clickaterminthediagramtodiveintothehierarchy(thetermishoistedtothetopofthehierarchydisplay).Thepathwidgetatthetopleftofthediagramshowsyouyourplaceinthehierarchyandletsyounavigatebackupthehierarchy.
Somedictionarieshavemultipleseparateinheritancehierarchies.Inthatcase,buttonsatthetopleftofthediagramletyouswitchbetweenthem.
Clickhereforthemeaningoftheiconstotheleftoftheattributenames.
DictionaryInfoPane SearchinDictionary
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow> TableofContents
SearchinDictionary
Youcansearchadictionarywithinadictionarywindow.Todoso:
Showthetoolbar(ifitisn’tshowingalready)andusetheSearchfield.ThemenuandkeyboardshortcutisSearch>LookUpDefinition.TypeatermtosearchforintheSearchfield,andpressReturntoinitiatethesearch.
Tospecifysearchoptions:
ClickthemagnifyingglassiconattheleftendoftheSearchfield.Youcanspecifytwokindsofoption:
Wordcontainment.YoucanspecifyEquals,Contains,BeginsWith,orEndsWith.
Wheretolook.Thisisdividedintotwosections.
Whatpartoftheinfotosearchin:Names,Descriptions,Synonyms,and/orAppleeventcodes.Forexample,ifyou’researchingforatermbyname,youmightwanttodisableDescription,asenablingitcanleadtofalsepositives.
Whatkindsoftermtosearchin:Commands,Events,Classes,Records,Types,Enumerations.
Searchresultsaredisplayedinplaceoftheterminologylistattheleftofthedictionarywindow.Resultsaregroupedalphabeticallyintorelevancerankings.Clickalistingtodisplayitintheinfopane.Thus,searchingisanotherwaytonavigatethedictionary.
Toremovesearchresultsandrestoretheterminologylist:
ClicktheXiconattherightendoftheSearchfield(orclickintheSearchfieldandpresstheEsckey).
Anotherwaytosearchthedictionaryisfromascriptwindow,throughthedictionariesinspector.
HierarchiesandDiagrams LookUpDefinition
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow> TableofContents
LookUpDefinition
Youcansearchadictionaryfromascriptwindow,withouthavingtoswitchtoadictionarywindow.Todoso,usethedictionariesinspector.
Therearetwoapproaches:
Selectatermwithinthescript’stext,andchooseSearch>LookUpDefinition.
Showthedictionariesinspector(chooseView>InspectorsTab,orclickthethirdShowbuttoninthescriptwindowtoolbar),enteraterminthesearchfield,andpressReturntoperformthesearch.
Searchresultsappearinthedictionariesinspector.Thelistissimilartothelistofsearchresultsthatwouldappearfromsearchinginadictionarywindow,andtheiconsforthekindsoftermarethesame.Thedifferenceisthatyouhavetheabilitytosearchthedictionariesofmultipleapplicationsatonce.
Forsearchoptions,clickthemagnifyingglassiconinthedictionariesinspectorsearchfield.Theoptionsarelikethesearchoptionswhenyou’researchingadictionaryinadictionarywindow,withtheadditionalabilitytospecifywhatdictionariestosearch.Youcansearchinthedictionaryof:
Thetelltarget.Thisistheapplicationtargetedattheinsertionpointinthescript.
AnyofthecategoriesofapplicationlistedinthedictionarieslistintheDictionarywindowandthedictionariesinspector:ScriptingAdditions,Running,Recent,Favorites,andAll.
Searchingthedictionarieslistcanbetime-consumingthefirsttimeyoudoit,becausedictionariesmustbeloadedandapplicationsmayhavetobelaunched.Butitwillbefastafterthatbecausethedictionaryiscached(unlessyou’veturnedoffthatfeatureintheDictionarypreferences).Whenyoustarttosearchdictionaries,adialogwillappearwarningyouofanyapplicationsthatmustbelaunchedinordertoloadtheirdictionaries,givingyouachancetopreventanyoralloftheseapplicationsfromlaunching(inwhichcasetheirdictionarieswillnotbesearchedorcached).
HavingperformedasearchintheLookUpDefinitioninspector,andhavingobtainedresults,todisplayaresultinitsdictionary:
Selecttheresult.TheinfoforthattermisshowninasplitpaneatthebottomoftheLookUpDefinitioninspector.
Double-clicktheresult.Theinfoforthattermisshowninthefrontmostdictionarywindow.
SearchinDictionary BackandForward
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow> TableofContents
BackandForward
Asyouworkwithadictionarywindow,thewindowrememberseverythingdisplayedintheinfopane.It’sasifeachdisplayintheinfopanewereawebpage.Asinawebbrowser,youcangobacktopreviouslyviewed“pages”,andthenforwardagain.Todoso:
ChooseDictionary>GoBackorDictionary>GoForward(orusetheconvenientkeyboardshortcuts).
Or,usetheBack/Forwardbuttonsinthedictionarywindow’stoolbar.
LookUpDefinition MiscellaneousDictionaryActions
ScriptDebuggerHelp>Explore>Dictionary>DictionaryWindow> TableofContents
MiscellaneousDictionaryActions
Thispagediscussessomemiscellaneousactionsthatyoucanperforminadictionarywindow.
PasteTell.Youcaninsertatellblockintoyourscript(atthecurrentinsertionpointinthefrontmostscriptwindow),targetingtheapplicationwhosedictionaryyouarecurrentlylookingat.Todoso:
ClickthePasteTellbuttoninthedictionarywindowtoolbar.
Or,chooseDictionary>PasteTellXXX.
What’spasteddependsonwhat’sbeingviewedorselectedinthedictionarywindow:
Ifwhatyou’relookingatinthedictionaryisacommand,atemplateforgivingthatcommandwillbeinserted.
Ifwhatyou’relookingatinthedictionaryisanevent,atemplateforaneventhandlerforreceivingthateventwillbeinserted.
Otherwise,asimpletellblockwillbeinserted.
Yourexistingcodewillnotbeoverwritten.SoPasteTellisalwayssafe(nondestructive).
IfyouholddowntheOptionkey,orifnoscriptwindowisopen,anewscriptwindowiscreatedandthetellblockisinserted.
Youcanpasteatellblockforanyapplicationshowninthedictionarieslist:
Control-clickonitandchoosePasteTellXXXfromthecontextualmenu.
ThereareotherwaystoissueaPasteTellcommand.
LaunchorActivate.Youcanstartuptheapplicationwhosedictionaryyouarelookingat,or,ifit’salreadyrunning,youcanbringittothefront.UsetheLaunchorActivatebuttoninthedictionarywindowtoolbar(theyarethesamebutton),orchooseDictionary>LaunchXXXorDictionary>ActivateXXX(theyarethesamemenuitem),where“XXX”isthenameoftheapplication.
Youcanlaunchoractivateanyapplicationshowninthedictionarieslist:
Control-clickonitandchooseLaunchXXXorActivateXXXfromthecontextualmenu.
Quit.Iftheapplicationwhosedictionaryyouarelookingatisrunning,youcanmakeitquit.UsetheQuitbuttoninthedictionarywindowtoolbar,orchooseDictionary>QuitXXX,where“XXX”isthenameoftheapplication.
IfyoudothatintheFinder’sdictionary,you’llgetawarningdialog,sincequittingtheFinderisnotsomethingoneusuallywantstodo.IfyoudoquittheFinder,youcanrelaunchitbyclickingtheLaunchbutton.
Youcanquitanyapplicationshowninthedictionarieslist:
Control-clickonitandchooseQuitXXXfromthecontextualmenu.
RevealinFinder.TorevealintheFindertheapplicationyou’recurrentlyworkingwithinadictionarywindow,chooseFile>RevealXXXinFinder,where“XXX”isthenameoftheapplication.
Youcanrevealanyapplicationshowninthedictionarieslist:
Control-clickonitandchooseRevealXXXinFinderfromthecontextualmenu.
PasteTermsBlock.Youcanpasteatermsblock(usingtermsfromapplication)foranyapplicationshowninthedictionarieslist:
Control-clickonitandchoosePasteUsingTermsFromXXX.
BackandForward
ScriptDebuggerHelp>Explore>Dictionary> TableofContents
ApplicationExplorer
Theexplorerinthedictionarywindowletsyouprobetheactualcurrentobjectsofarunningscriptableapplication,inrealtime.Youcaneasilydiscoveranapplication’sobjectmodel,insertobjectreferencesintoyourscripts,andseethevaluesofobjectproperties—andevenchangethosevalues.
DictionaryexplorersareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Toseeadictionarywindow’sexplorer:
OpenadictionarywindowandchooseDictionary>ShowExplorer(orclicktheExplorerbuttoninthetoolbar).
Theresultisthatanobjectexplorerreplacestheterminologylist(orobjectmodeldiagram)andinfopaneinthedictionarywindow.Theobjectbeingexploredistheentirerunningapplication.
TheapplicationexplorerinthedictionarywindowisoneofmanyobjectexplorerviewsthatScriptDebuggerprovides.Clickheretolearnaboutexplorers.
Thetellcontextinspectorinascriptwindowcanfunctionasaminiatureversionoftheapplicationexplorer.Itprovidesamorefocussedwaytoprobeanapplication’scurrentobjects.Itwatcheswhereyouareworkinginascriptwindowandprobestheattributesofthecurrenttelltarget.
FurtherDetails:
TellContextInspector
DictionaryWindow
ScriptDebuggerHelp>Explore>Dictionary>ApplicationExplorer> TableofContents
TellContextInspector
Thetellcontextinspectorisaliveoutlinerexploringthecurrentlytargetedapplicationorobjectinyourscript.Thinkofitasanautomaticallypopulateddictionaryexplorer,orastheBestviewoftheresultpanewithoutyourhavingtorunorevencompilethescript.
ThetellcontextinspectorisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
ThetellcontextinspectorisintheInspectorstabofascriptwindow.Toseethetellcontextinspector:
ChooseView>InspectorsTab.
Or,clickthethirdShowbuttoninthescriptwindowtoolbar.
Thetellcontextinspectorliststhecurrentelementsandpropertiesoftheapplicationorobjecttargetedatthepointwhereyouareworkinginyourscript(thecurrenttellcontext).Itautomaticallydrillsdownalongwithyourscriptintosuccessivelydeeperlevelsoftellcontext.Forexample:
tellapplication"BBEdit"telldocument1getword1endtellendtell
Inthatscript:
Ifyouselectinthesecondline,thetellcontextinspectorshowstheelementsandpropertiesofBBEdit(theapplicationobject).
Ifyouselectinthethirdline,thetellcontextinspectorshowstheelementsandpropertiesofdocument1ofapplication"BBEdit".
Topasteatellblockintothecurrentscript:
ClickthePasteTellbutton.HoldOptiontopasteintoanewscript.
Toopenadictionarywindowforthecurrentlytargetedapplication:
ClicktheDictionarybutton.
Thetellcontextinspectorisanoutliner,withallthatthatentails.
ScriptDebuggerHelp>Explore> TableofContents
Explorer
AnexplorerisScriptDebugger’spowerful,flexible,interactivewayofdisplayinganAppleScriptvalue.ExplorersappearinmanyplacesinScriptDebugger’sinterface.
ExplorersareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Afull-fledgedexplorercanbedisplayedinanyofthreeviews.
Bestview.Thisviewis“best”becauseitismostinformative.Ifavaluehaspropertiesorelements(orboth),Bestviewshowsanoutliner,whichisScriptDebugger’spowerfulinterfaceforinteractivestudyofacomplexvalue.Therecanbemorethanonebestview;forexample,adate’sBestviewmightshowbothanoutlinerandadatewidget.
Sourceview.ThisviewshowsthevalueastheAppleScriptlanguagedescribesit.
AEPrintview.ThisviewshowsthevalueasanAppleeventdescribesit.
Toswitchamongviews:
ChooseView>BestView,View>SourceView,orView>AEPrintView.
Or,clicktheBest,Source,orAEPrintbuttonatthetoprightoftheexplorer.
Youcanshowmorethanoneviewatonce.Todoso,holdShiftasyouswitchviews.Theresultisasplit-panedisplayofmultipleviews.
Variousexplorerviewoptionsandactionsmaybeavailable,dependingonwhatviewisdisplayedandwhatkindofvalueisbeingviewed.
FurtherDetails:
WhereExplorersAppearExplorerWindowsBestSourceAEPrintExplorerViewOptionsandActions
Dictionary
ScriptDebuggerHelp>Explore>Explorer> TableofContents
WhereExplorersAppear
Explorersappear,orcanbegenerated,inmanypartsoftheScriptDebuggerinterface.Basically,anexplorerisScriptDebugger’swayoflettingyouunderstandandworkwithanAppleScriptvalue,sowhereveravalueneedstobeshown,anexplorerisused.
ExplorersareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Forexample:
TheexplorerthatappearsinadictionarywindowwhenyouchooseDictionary>ShowExplorer(orclicktheExplorerbuttoninthedictionarywindow’stoolbar)isanexplorer.Theobjectbeingexploredisarunningscriptableapplication.
Theresultpaneinascriptwindowisanexplorer.Theobjectbeingexploredistheresultreturnedbyexecutingascript(or,ifyou’redebugging,thevaluereturnedbythemostrecentlyexecutedlineofcode).
Theeventlog’ssecondcolumn(theLogResultcolumn)isanexplorer.TheobjectbeingexploredistheresultreturnedbytheAppleeventselectedinthefirstcolumn(theeventlist).
Anerrordialogmayincludeanexplorer.Theobjectbeingexploredistheproblematicvalue.
Inotherplacesintheinterface,asortof“partialexplorer”appears(theBestviewoutlineronly,withnochoiceofviewsandnopathwidget):
Thetellcontextinspectorinascriptwindowistheoutlinerofanexplorer.Theobjectbeingexploredistheobjectbeingtargetedbytheinnermosttellblocksurroundingthecurrentselectioninthescript.
Thevariablespaneinascriptwindowistheoutlinerofanexplorer.Theobjectbeingexploredisthetop-levelscriptobject.
Anexplorercanalsobegeneratedasaseparatewindow—anexplorerwindow.
NOTE:Whenthevaluebeingexploredbyanexplorerhaschanged,aredbarappearsatthetopoftheexplorer.Forexample,inascriptwindow,theresultpaneshowsaredbaraftereachtimeyourunthescript,becauseanewlygeneratedresultisbeingexplored.Anexplorerwindowisanothercommoncase.
ExplorerWindows
ScriptDebuggerHelp>Explore>Explorer> TableofContents
ExplorerWindows
Anexplorercanbegeneratedasaseparatewindow—anexplorerwindow.
ExplorerwindowsareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Forexample:
Theresultassociatedwithscriptwindowcanappearasaseparateexplorerwindow.
YoucansetanExecutionpreferencesothatthishappensautomatically(“Showresultwhenscriptspauseorend”>“ShowResultExplorerWindow”).
Or,chooseScript>ShowResultExplorerWindow.
Or,Control-clickinthegreybaratthetopoftheresultpaneandchooseShowResultExplorerWindowfromthecontextualmenu.
TheresultofanAppleeventrecordedintheeventlogcanappearasaseparateexplorerwindow.
Double-clickaneventinthelogtoopenitsresultasanexplorerwindow.
Or,chooseScript>ShowResultExplorerWindow.
Or,Control-clicktheeventandchooseShowEventLogResultExplorer.
Avaluewithintheoutlinerofanyexplorercanappearasaseparateexplorerwindow.Thisincludesanoutlinerinanexplorerwindow.Thus,it’spossibletogenerateaseries,orcascade,ofexplorerwindows.
Control-clickthevalueandchooseOpenExplorerWindowfromthecontextualmenu.
Or,selectthevalueandchooseFile>OpenExplorerWindow.
Inapartialexplorer,youcanalternativelydouble-clickthevalue.(Inafull-fledgedexplorer,double-clickingavaluehoistsit.)
Aseparateexplorerwindow,oracascadeofseparateexplorerwindows,canbeawaytofocusmoreeasilyontheinformationthatinterestsyou.Thisisdemonstratedintheillustrationbelow,whichshowsthreeexplorerwindowsspawnedsuccessivelyfromadictionaryexplorer(lefttoright):
1. targetofFinderwindow"Explorerstuff"
2. foldersofthattarget
3. folder"Alertsandpanels"ofthosefolders
4. creationdateofthatfolder
NOTE:Anexplorerwindowhasatoolbar,butthetoolbarsarehiddenintheabovescreenshot,tosavespace.
Anexplorerwindowmaintainsitslinkagebacktotheexplorerfromwhichitwasspawned.Thislinkageexpressesthefullidentityofthevaluebeingexplored.Toseeanexplorerwindow’sidentity:
Control-clicktheexplorerwindow’stitle.
Apop-upmenuappears.Eachsuccessiveiteminthemenuisastepuptheobjectmodel,asiftherewereanimplicitofbetweenthem.Forexample,intheillustrationbelow,theexplorerwindowisshowingthecreationdateoffolder"Alertsandpanels"oftargetofFinderwindow"Alertsandpanels"(oftheapplication“Finder”).
Moreover,eachmenuitemitselfhasahierarchicalmenuexploringtheentireobjectmodelofthatobject.ThisisexactlyparalleltothehierarchicalmenuattachedtothePasteTellmenuitem.
Anexplorerwindowremains“live”:itchangesifthevaluebeingexploredchanges,providedScriptDebugger“knows”aboutthechange.Forexample,anexplorerwindowspawnedofffromascriptwindow’sresultpaneorvariablespanemaychangeitsvaluespontaneously,becauseScriptDebugger“knows”whenthesevaluesneedtoberefreshed(e.g.,youranthescriptagain).Inothercases,youmightneedtoaskScriptDebuggertoreloadanexplorer:chooseDictionary>Reload.
Anexplorerwindowmayalsoclosespontaneouslyifthevaluebeingexploredceasestoexist.Forinstance,anexplorerwindowthatisexploringavariablefromthevariablespanewillclosewhenthevariablegoesoutofscope.Similarly,anexplorerwindowthatisexploringanelementofaclasswillcloseifthatclassisrefreshedandtheelementnolongerexists.
Tosetdefaultsforthesize,view,anddisplayoptionsofexplorerwindows:
Summonanexplorerwindow,setitssizeanddisplayoptionsasdesired,andchooseWindow>SetDefaultExplorerSize&State.
WhereExplorersAppear Best
ScriptDebuggerHelp>Explore>Explorer> TableofContents
Best
BestviewinanexplorerisScriptDebugger’smostpowerfulwayforyoutoexamine,understand,andinteractwithavalue.
Bestviewisparticularlysignificantinthefollowingcases:
Ifthevaluebeingviewedisanobjectreference,theobject’selementsandpropertiesareshownasaninteractiveoutliner.Youcandiscoverobjectattributesandtheirvalues,learnhowtoreferenceanobjectattribute,divedeeperintoattributesthatarethemselvesobjects,andmuchmore.ThisisoneofScriptDebugger’skeyfeatures.
Similarly,ifthevalueisacollection(alistorarecord),theitemsofthecollectionaredisplayedinanoutliner.
Ifthevalueisavalidaliasorfileobjectreference,itisshownasapathnamethatcanbedisplayedindifferentstyles:
HFS(colon-delimited)
POSIX(slash-delimited)
Finder(i.e.,astheFinderwouldrefertoit)
YoucanalsogetaQuickLookviewoftheitem(chooseFile>QuickLook,orpresstheQuickLookbutton),orviewtheitemintheFinder(chooseFile>RevealXXXinFinder,orpresstheFinderbutton).
Ifthevalueisimagedata,itisshownasanimage.
IfthevalueisHTMLsource,itisoptionallyrenderedasinabrowser.ThisbehaviorisgovernedbyaDictionarypreference,“RenderHTMLstringvaluesasHTMLpage”.
Ifthevalueisadate,itisshownasadatechooser,usuallyalongwithanoutlinershowingitsproperties.
Ifthevalueisastring,itisshowndirectlyastext(asopposedtosourceview,whichshowsaquotedstring,possiblycontainingescapedcharacters).
BestviewalsodisplaysmanytypesofObjective-Cvaluecoherently,inAppleScriptObjCcode,withoutyourhavingtocoercethemtoAppleScripttypes.Forexample,herewegenerateanNSArrayofNSStrings:
useframework"Foundation"setstocurrentapplication'sNSString'sstringWithString:"thecatsatonthemat"setarrtos'scomponentsSeparatedByString:""
Theresultisanoutlinerdisplayingtheelementsofthearray:
Readontolearnabouthowtouseanoutliner.
Youcanshowmorethanoneviewatonce.Todoso,holdShiftasyouswitchviews.Theresultisasplit-panedisplayofmultipleviews.
FurtherDetails:
OutlinerOutlinerEditing
ExplorerWindows Source
ScriptDebuggerHelp>Explore>Explorer>Best> TableofContents
Outliner
Anoutlinerisaninteractivehierarchicaldisplayofanobject’spropertiesandelements.AnoutlinermayappearasBestviewofanexplorerorbyitselfasaseparateview.
Thedisplayisintwocolumns:thenameofanelementorproperty,andthevalueofthatelementorproperty.
Triangles
Anylineinanoutlinerwhosevalueisitselfanobjectwithelementsandpropertiesisindicatedbyatriangle.Clickatriangletorevealorhidetheelementsandpropertiesofthatobject.(Alternatively,selectalinecontainingatriangleandpressRightArroworLeftArrow.)Thechiefcasesofvalueswithtrianglesare:
Anelementcollection.Elementcollectionsaredisplayedbeforeproperties,inboldfacewithapluralname.Forexample,intheFinder,afoldermayhaveitems.Thevalueisshownastheelementcount(e.g.,“8items”).
Anobjectwithproperties.Forexample,adatevaluehasproperties.IntheFinder,anitem’scontainerisafolderandhaselementsandproperties.Thevalueisareferencetotheobject,asprovidedbytheowningapplication.
Alistorrecord.ThevaluedependsonaDictionarypreference,“Showcontentsoflistandrecordvalues”:ifchecked,thevalueisaliterallistsimilartoSourceview;ifunchecked,thevalueisshownastheitemcount(e.g.,“listof2items”).
Ascriptobject.Themostcommoncaseisthevariablespane,whichitselfexploresascriptobject(thescriptitself)anddisplaysadditionalscriptobjectssuchasparentandAppleScript.
ElementCollections
Whenyourevealtheelementsofacollection,theremaybeashortdelayasScriptDebuggergathersinformationaboutthem.Iftherearemanyelementsinacollection,ScriptDebuggermaysavetime(andAppleevents)byceasingtogatherinformationaboutthembeyondacertainnumber.Forexample,runthisscriptandexaminetheBestoutlinerintheresultspane:
tellapplication"Finder"tellhomegetfolder"Library"endtellendtell
Ifyouclickthetrianglenexttoitems,someitemsareshowninitially,followedbyaShowMoreItemsbutton.ThenumberofitemsshowninitiallyinthesesituationsisgovernedbyaDictionarypreference,“Shownelementsatatime.”
Elementsofacollectionareinitiallygatheredwithreferencetosomeparticularspecifier.ThedefaultspecifierisgovernedbyaDictionarypreference,the“AccessElementsby”pop-upmenu.YouroptionsareIndex,ID,andName.Youcanchangethereferencespecifierforanelementcollectionusingthepop-upmenunexttothecollection’snameintheoutliner.
Ifareferencespecifierfails(becausethescriptableapplicationdoesn’trespondtoit),ScriptDebuggerautomaticallyfallsbackonadifferentspecifieranddisplaysanexclamation-markicon( ).Forexample,theFinderdoesn’timplementgatheringafolder’sitemsbyIDandhastroublewithitemoflistexpressions;ScriptDebuggerworks
aroundthisbehindthescenes,anddisplaystheexclamationmark.
Thesamepop-upmenunexttothecollection’snamecanalsobeusedtoreplacethecollectiondisplayedwithasingleelement.YourchoicesareFirst,Middle,Last,andAny.
Reloading
Gatheringoutlinerinformationcanbeexpensiveandtime-consuming(itinvolvessendingalotofAppleevents),soScriptDebuggergathersinformationonlywhenithasto:
Whenanoutlinerinitiallyappears,onlyinformationvisiblewithinthepaneorwindowisgathered.
Whenyouscrollanoutliner,revealedinformationisgatheredifithasn’tbeengatheredalready.
Whenyouexpandatriangle,revealedinformationisgathered,uptothelimitspecifiedby“Shownelementsatatime,”asdescribedabove;whenyouclicktheShowMorebutton,moreinformationisgathered.
Outlinersconnectedwithyourscript,suchastheresultpaneandthevariablespane,automaticallyrefreshtheirvisiblecontentswhenyourunthescriptorstepwhiledebugging.Otherwise,anoutlinerisnotlive.Ifthesituationinthetargetapplicationchanges,youcanmanuallyrequestthattheoutlinerrefreshitself.Todoso:
SelectalinewithintheoutlinerandchooseDictionary>Reload(orchooseReloadfromaline’scontextualmenu).Thevalueofthatline,andeverythingexposedthat’shierarchicallydeeper,willbegatheredafresh.
Youcanalsoasktoreloadtheentireoutliner.(Butbecareful,becausethismaycauseScriptDebuggertosendthetargetapplicationalotofAppleevents.)Todoso:
HoldOptionandchooseDictionary>Reload(AllItems).Or,chooseReloadAllfromthecontextualmenu.
NavigatinganOutliner
WhenitappearsastheBestviewofanexplorer,avalueoutlinerhasapathwidget,alongwithbackandforthbuttons.Ifyoudouble-clickanylinewithintheoutline,thatlineishoistedsothattheexplorerisnowexploringthatvalue.
Ina“partialexplorer”(withnopathwidgetorBest/Source/AEPrintbutton),double-clickingalinespawnsoffaseparateexplorerwindow.
Thepathwidgetdisplaysareferencetowhatisbeingexplored.Whenavaluewithinanexplorerishoisted,thepathwidgetappendsareferencetothatvalue.Thus,thepathwidgetalwaysdisplaysachainofreferences(equivalenttoanestoftellblocks)showinghowyouarrivedatthevaluenowbeingexplored.Thehighlightedreferenceinthepathwidgetistheonecurrentlybeingexplored.
Thereferencesinthepathwidgetarebuttons.Tonavigatebackupthechainofreferences:
Clickabuttontotheleftofthehighlightedbuttoninthepathwidget.
Whenyounavigateupthechainofreferencesusingthepathwidget,thepathwidgetcontinuestoshowthefullchain,incaseyouwanttonavigatebackdownitagain.Tonavigatebackdownthechainofreferences:
Clickabuttontotherightofthehighlightedbuttoninthepathwidget.
ScriptDebuggeralsorememberseachexploredobject(theexplorerhistorylist).Toexploreagainapreviouslyexploredobject:
ClicktheBackbutton,orchooseDictionary>GoBack.
AfterusingtheBackbutton,youcanusetheForwardbutton,orchooseDictionary>GoForward,tomovetheotherwaythroughthehistorylist.
Filtering
Youcanfiltertheoutlinetoshowonlycertainattributes.Todoso,usethebuttonsinthescopebar.
Yourchoicesare:
FilledElements.Ifhighlighted(dark),elementcollectionsthatactuallycontainelementsareshown(elementcountisnonzero).
EmptyElements.Ifhighlighted(dark),elementcollectionsthatcontainnoactualelementsareshown(elementcountiszero).
Properties.Ifhighlighted(dark),propertiesareshown.
IfbothFilledElementsandEmptyElementsarehighlighted,allelementcollectionsareshown.IfneitherFilledElementsnorEmptyElementarehighlighted,noelementcollectionsareshown.Ifnoneoftheabovebuttonsarehighlighted,theoutlinerwillbeempty.
Tohighlightallthreeoftheabovebuttonsquicklyandshowthecompleteoutline,chooseShowAllItems,Properties&Elementsfromthecontextualmenu.
Asecondsetofbuttonsletsyouchoosetoshowitemswithrespecttorecentchangesinvalue:
Changed.Ifhighlighted(dark),recentlychangedvaluesaredisplayed(inred).
Unchanged.Ifhighlighted(dark),theinversesetofvaluesfromChangedaredisplayed.
IfneitherChangednorUnchangedishighlighted,theoutlinerwillbeempty.
Thescopebarcanbeshownorhiddenatwill.Everyexplorerhasascopebar,including“partialexplorers”likethevariablespaneandeventheexpressionspane;thescopebaristhesepartialexplorersishiddenbydefault,tosavespace,butyoucanshowit.Totogglethevisibilityofthescopebar:
ChooseShow/HideScopeBarfromthecontextualmenu.
Dictionary
Youcanjumpfromalineoftheoutlinetothedictionaryentryforthatterm.Todoso:
Control-clickonthelineoftheoutlineandchooseShowDefinitionfromthecontextualmenu.
Thedefinitionforthatclass(or,ifit’saproperty,fortheclassofwhichthisisaproperty)willbedisplayedinadictionarywindow.
Raw(Chevron)Syntax
YoucantogglebetweenEnglishterminologyandrawAppleeventcodesinanoutliner.Todoso:
ChooseShowRaw(Chevron)Syntaxfromthecontextualmenu.
Badges
Namesinanoutlinerarebadgedaccordingtotheirtype.
Objectvaluesinanoutlinerarebadgedwiththeiconoftheowningapplication.
Read-onlyscalarvaluesinanoutlinerarebadgedwithacrossed-outpencilicon( ).
SpecialValues
Errorvalues(showninorange,withastop-signicon)inanexplorerarenotproblematic.TheyindicatethatScriptDebuggeraskedforanelementorpropertyandtheapplicationresponded,ingoodorder,witharuntimeerror.Thisisavalidresponsefromtheapplication.
Amissingvalueresultisalsoavalidresponsefromtheapplication.
An«empty»valueissuppliedbyScriptDebuggertoindicatethattheapplicationhasfailedtoreturnanyvalueatall.Thisisusefulinformation,becauseifyouassignsuchanonvaluetoavariableinascript,thatvariablewillbeundefined.
Incertainspecialcases,suchastheentirecontentspropertyoftheFinder,ScriptDebuggersuppliesanotloadedvaluesoasnottorequestevaluationofapropertywhosevaluecouldtaketheapplicationaverylongtimetoreturn.
EditinginanOutliner
Readontolearnhowyoucaneditavalueoredityourscriptusinganexplorer’soutliner.
OutlinerEditing
ScriptDebuggerHelp>Explore>Explorer>Best> TableofContents
OutlinerEditing
Inadditiontoviewingvaluesinanoutliner,youcaneditthosevalues,andusethosevaluestohelpeditascript.Insomecasesitcanbeusefultodeletethemaltogether,whentestingascript.
ChangingaValue
Inanoutliner,valuesarewriteable,andcanbechanged—unlesstheyarebadgedwiththecrossed-outpencilicon( )indicatingthattheyarenotwriteable.
Becareful!Whenyouchangethevalueofapropertyultimatelybelongingtoanapplication,youarechangingrealworldfactsaboutthatapplicationinrealtime.Forexample,ifyouchangethevalueofthenamepropertyofadocumentfileobjectbelongingtotheFinder,youchangetheactualnameofanactualfile.
Ontheotherhand,whenyou’redebuggingascriptandyouusethisfeaturetoalteravaluebelongingtothescript(suchasavariable),thisfeatureisharmlessandextremelyuseful.
Toeditasimplescalarvalue(astringornumber):
SelectthelineandpressReturn.Alternatively,chooseEditValuefromthecontextualmenu.
TheentryintheValuecolumnwillbecomeeditable.Whenyou’redone:
PressReturnorclickelsewheretomakeyourchangetakeeffect.
Ifavalueisaneditableenumeration,itisrepresentedasapop-upmenulistingthepossibleenumeratorvalues.Toeditthevalue:
Chooseanewvaluefromthepop-upmenu.
Toeditalistorrecord:
Todeleteanitem,selectitandpressDelete.
Tomoveanitem,dragittoitsnewposition.Dragitoveranexistingitemtoreplaceit,ordragitbeforeorafteranotheritemtoinsertit.
Tocopyanitem,dragittoitsnewpositionwhileholdingdowntheOptionkey.Dragitoveranexistingitemtoreplaceit,ordragitbeforeorafteranotheritemtoinsertthecopy.
YoucanalsodeleteavariableorscriptobjectpropertybyselectingitandpressingDelete.
EditingaScript
Alineofanoutlinerrepresentsareferencetoanelementorproperty(oravariable).YoucancapturethisreferenceasAppleScriptcode,touseitinascript.Toturnalineofanoutlinerintoareference:
Control-clickalineoftheoutline,andchoosePasteTellfromthecontextualmenu.Areferencetothatobjectispastedintothefrontmostscript.HoldOptiontopasteintoanewscript.
Or,drag-and-dropthelinefromtheoutlinerintoascriptwindow.
Or,inadictionarywindow,selecttheline;thenpressthePasteTellbuttoninthetoolbar,orchooseDictionary>PasteTellXXX(where“XXX”isthenameoftheapplication).HoldOptiontocreateandpasteintoanewscriptwindow.
SelectthelineandchooseEdit>Copy.Thenpastewhereveryouwantthereferencetogo.
Or,chooseCopyReferencefromthecontextualmenu.Thenpastewhereveryouwantthereferencetogo.
Alineofanoutlineralsorepresentsthevalueofwhateveritisareferenceto.Youcancapturethisvalue.Toturnalineofanoutlinerintoavalue:
Selecttheline,holdShift,andchooseEdit>CopyValue.Thenpastewhereveryouwantthevaluetogo.
Or,chooseCopyValuefromthecontextualmenu.Thenpastewhereveryouwantthevaluetogo.
Outliner
ScriptDebuggerHelp>Explore>Explorer> TableofContents
Source
Sourceviewinavalueexplorerpresentsthevalueasthesourcelanguage(AppleScript)wouldpresentit.
Forexample:
InBestview,anobjectreferenceisanoutliner.InSourceview,anobjectreferenceisthereference.
InBestview,alistisshownasanoutliner.InSourceview,alistisdelimitedbycurlybraces.
InBestview,astringisshownasthetextofthestring.InSourceview,astringisdelimitedbyquotationmarks.
WhenanexplorerpresentsanObjective-CobjectvaluereturnedbyAppleScriptObjC,sourceviewbecomesDescview,where“Desc”referstoObjective-C’sdescriptionmethod.Ineffect,ScriptDebuggershowsyoutheobjectasNSLogwouldshowitinXcode’sconsole.Forexample:
useframework"Foundation"setftocurrentapplication'sNSURLComponents'scomponentsWithString:"http://www.example.com"
TheresultisdisplayedinDescviewas:
Youcanshowmorethanoneviewatonce.Todoso,holdShiftasyouswitchviews.Theresultisasplit-panedisplayofmultipleviews.
Best AEPrint
ScriptDebuggerHelp>Explore>Explorer> TableofContents
AEPrint
AEPrintviewinavalueexplorershowsthevalueasitwouldbecommunicatedthroughanAppleevent.
Here’stheFinder’sdesktopinAEPrintview:
'obj'{'form':'prop','want':'prop','seld':'desk','from':[0x0,e00e"Finder"]}
Intheeventlog,AEPrintviewshowstheAppleeventmessagessenttoascriptableapplication,aswellasthereplies.Here,we’veaskedtheFinderforitswindow1:
'core'\'getd'{'----':'obj'{'form':'indx','want':'cwin','seld':1,'from':null()},&'csig':65536}
'obj'{'want':'brow','from':[0x0,e00e"Finder"],'form':'ID','seld':214}
Ifyou’renotsomeonewhoknowsorcaresaboutAEPrintformatandrawAppleevents,thendon’tworryaboutAEPrintview.
Youcanshowmorethanoneviewatonce.Todoso,holdShiftasyouswitchviews.Theresultisasplit-panedisplayofmultipleviews.
Source ExplorerViewOptionsandActions
ScriptDebuggerHelp>Explore>Explorer> TableofContents
ExplorerViewOptionsandActions
Therearevariousoptionsforhowmaterialisdisplayedinanexplorer,andvariousactionsyoucanperform.Whatoptionsandactionsareavailablewilldependonwhatviewyou’rein(Best,Source,orAEPrint)andwhatsortofvalueisbeingexplored.
Pretty-printing
Pretty-printingarrangestextinlines,withindentations,tomakeavalueeasiertoread.Forexample,pretty-printingmakesthedifferencebetweenthis(nopretty-printing):
{1,2,3}
andthis(pretty-printing):
{1,2,3}
Tocontrolpretty-printing:
ChooseView>PrettyPrint.
Or,Control-clickandchoosePrettyPrintfromthecontextualmenu.
Or,clickthePrettyPrinticon attheupperrightoftheview.
Ifthemenuitemischeckedortheiconisdimmed,pretty-printingisturnedon.
OtherDisplayOptions
Otherdisplayoptionsareanalogoustothedisplayoptionsforascriptwindow:
Youcantogglelinewrappingonoroff.ChooseView>WrapLinesorusethecontextualmenu.
Youcanshoworhidetabstops.ChooseView>ShowTabStopsorusethecontextualmenu.
Youcantogglewhetherinvisiblecharactersareshown.ChooseView>ShowInvisiblesorusethecontextualmenu.
Ifinvisiblecharactersareshown,youcantogglewhetherspacesareshown.ChooseView>ShowSpacesorusethecontextualmenu.
AEPrint
ScriptDebuggerHelp> TableofContents
Develop
ScriptDebuggergivesyoupowerful,uniquetoolstohelpyoudevelopyourAppleScriptcode.Fromashortone-offscripttoacomplicatedprogram,you’lleasilyandquicklycreatecodethatworks.
YoucanthinkoftheAppleScriptdevelopmentcycleinthreestages:
Edityourcode.Entercode,viewit,navigateit,searchit.
Runyourcode.Compilecode,executeit,timeit,gettheresult,andlogAppleeventcommunicationbetweenyourcodeandscriptableapplications.
Debugyourcode.Stepthroughcode,setbreakpoints,watchvalueschangeasyourcodeprogresses.Understandwhatyourcodedoes,linebyline.
FurtherDetails:
EditRunDebug
Explore Reference
ScriptDebuggerHelp>Develop> TableofContents
Edit
ScriptDebuggerisadedicatededitorforAppleScriptprograms.It’sdesignedtomakeitaseasyaspossibleforyoutoedityourAppleScriptcode.
Gettoknowthescriptwindow.
Learnabouteditingandnavigatinginthescriptwindow.
FurtherDetails:
ScriptWindowEditingandNavigation
Run
ScriptDebuggerHelp>Develop>Edit> TableofContents
ScriptWindow
MeetScriptDebugger’sscriptwindowenvironment.Thisiswhereyouwillview,edit,run,anddebuganyscriptsthatyoucreateoropen.
Herearethepartsofthescriptwindow:
1. Thetoolbar.
2. Thetabbar.Tabsletyouworkwithmultiplescriptsinonewindow.
3. Thenavigationbarand“tableofcontents”pop-upmenu.
Thenavigationbardescribeswherethecurrentselectionis.
Choosefromthepop-upmenu(the“tableofcontents”)tojumptheselectiontoahandlerorothertop-levelentity.
4. Thesplitandwrapicons.
5. Thetextarea.Thisiswhereyoueditthescript.Youcanalteryourviewofthescript’scontents.
6. Thegutter(thecolumnattheleftedgeofthewindow).Informationappearsinthegutter,suchas:
Marker“droplets”
Errormarks
Linenumbers(optional)
Breakpoints(whendebugging)
Codecoveragemarks(whendebugging)
Asecondaryguttercontainscodefoldingindicators.
7. Thepanesandinspectorstab.Itoccupiestherightsideofthewindow.WhatappearsheredependsuponyourchoicesintheViewmenuorthescriptwindow’stoolbar.Youcanseepanesandinspectorsonegroupatatime,oryoucanremovethepanesandinspectorstabentirely:
View>Result&VariablesTab(orthefirstShowbuttoninthescriptwindowtoolbar):
Theresultpane
Thevariablespane
Theexpressionspane
Thecallstackpane(whendebugging)
Thebreakpointspane(whendebugging)
View>ResourcesTab(orthesecondShowbuttoninthescriptwindowtoolbar):
Thescript’sdescription
Thebundleinspector(ifthescriptisinabundleformat)
View>InspectorsTab(orthethirdShowbuttoninthescriptwindowtoolbar):
Theclippingsinspector
Thedictionariesinspector
Thetellcontextinspector
Noneoftheabove:Thepanesandinspectorstabisremovedfromthewindow.Thiscanbeawaytosavespace.
8. Theeventlogpane.Itoccupiesthebottomofthewindow,belowthetextarea.YouwillseeitifyouhavechosenView>ShowEventLog.UsetheeventlogtoreceivemessagesfromyourscriptandtoviewAppleeventmessagesthatpassbetweenyourscriptandscriptableapplications.
9. Thestatusbar.Itisthebottomborderofthewindow,anddisplaysmessagesreportingthestatusofthemostrecentcompilationattempt,themostrecenterror,orthepausedstatusduringdebugging.Tocontrolthevisibilityofthestatusbar,chooseView>Show/HideStatusBar.
Thescriptwindowappearanceisconfigurable,soyoumightwanttosaveacertainsize,shape,position,andappearanceasthedefault,sothatwheneveryoucreateanewscript,ithasthelookthatyouprefer.
Ifascriptisopenforeditinginascriptwindowortab,youcanopenthesamescriptinanotherwindowwithoutdestroyingtheexistingwindowortab:chooseFile>OpeninNewWindow.Theresultisadocumentthat’sbeingeditedbymultiplewindowssimultaneously.Thisisagoodwaytoviewdifferenttabssimultaneously(forexample,youcanseetheResultpaneinonewindowandthedictionariesinspectorinanother).
FurtherDetails:
ViewOptionsinaScriptWindowDefaultScriptWindowSizeandState
EditingandNavigation
ScriptDebuggerHelp>Develop>Edit>ScriptWindow> TableofContents
ViewOptionsinaScriptWindow
ScriptDebuggerprovidesmanyoptionsforhelpingyouviewyourscriptinascriptwindow.
Besideschoosingwhethertowraplonglines,youcanalsoshoworhideinvisiblecharactersandspaces,seelinenumbersandtabstops,andevenviewyourscript’srawAppleeventcodes.
Manyoftheseoptionsapplyinothercontextsaswell,suchasvalueexplorers.
FurtherDetails:
LineWrappingInvisiblesSpacesLineNumbersTabStopsRaw(Chevron)Syntax
DefaultScriptWindowSizeandState
ScriptDebuggerHelp>Develop>Edit>ScriptWindow>ViewOptionsinaScriptWindow> TableofContents
LineWrapping
Howshouldlinesofyourscriptbedisplayedwhentheyaretoolongforthewidthofthetextarea?ScriptDebuggerletsyouchoosetoviewlonglinesaswrappedautomaticallyortoletlonglinesextendtotheright.Totogglelinewrapping:
Clickthewrapicon(attheupperrightofthetextarea).
Or,chooseView>WrapLines.
Or,chooseWrapLinesfromthecontextualmenu.
Ifthemenuitemischecked( ),linewrappingisturnedon.
Ifthemenuitemisunchecked( ),linewrappingisturnedoff,andlonglineswillextendtotherightandahorizontalscrollbarwillappearifnecessary.
Invisibles
ScriptDebuggerHelp>Develop>Edit>ScriptWindow>ViewOptionsinaScriptWindow> TableofContents
Invisibles
ScriptDebuggerletsyouseeinvisibletextcharacters,suchastabsandreturncharacters.Toseeinvisiblecharacters:
ChooseView>ShowInvisibles.
Or,chooseShowInvisiblesfromthecontextualmenu.
Ifthemenuitemischecked,invisiblesareshowing.
Showinginvisiblesisespeciallyhelpfulforviewingstringliterals.AppleScriptcompileswhitespaceliteralsintoliteralwhitespace,whichconcealstheiridentity.Forexample,thisscript:
setsto"\t\r"
compileslikethis:
setsto""
Nowyou’venoideawhatthatstringconsistsof.Tofindout,showinvisibles.
Thisisparticularlyusefulinthecaseoflineendings,whichcanpresentacomplicatingfactorinAppleScript,asexplainedhere.
LineWrapping Spaces
ScriptDebuggerHelp>Develop>Edit>ScriptWindow>ViewOptionsinaScriptWindow> TableofContents
Spaces
ScriptDebuggercanshowspacecharactersintext.Theyareshownassmalldots.Toshowspacecharacters:
Youmustfirstbeshowinginvisiblecharacters.Then:
ChooseView>ShowSpaces.
Or,chooseShowSpacesfromthecontextualmenu.
Ifthemenuitemischecked(andinvisiblesareshowing),spacesareshowing.
Invisibles LineNumbers
ScriptDebuggerHelp>Develop>Edit>ScriptWindow>ViewOptionsinaScriptWindow> TableofContents
LineNumbers
ScriptDebuggercandisplayyourscriptwithlinenumbersinthegutter.Totogglethevisibilityoflinenumbers:
ChooseView>ShowLineNumbers.
Or,chooseShowLineNumbersfromthecontextualmenu.
Ifthemenuitemischecked,linenumbersareshowing.
Thenavigationbaralsoshowslinenumbers,andyoucanjumptoalinebyitsnumber.
Spaces TabStops
ScriptDebuggerHelp>Develop>Edit>ScriptWindow>ViewOptionsinaScriptWindow> TableofContents
TabStops
ScriptDebuggercandisplaytabstopsintext.Tabstopsarethehorizontalpointsatwhichindentationautomaticallyoccurswhenascriptiscompiledorwhenavalueispretty-printed.Thepositionsofthetabstopsareshownbyverticallinesbehindthetext.Toshowtabstops:
ChooseView>ShowTabStops.
Or,chooseShowTabStopsfromthecontextualmenu.
Ifthemenuitemischecked,tabstopsareshowing.
Thesizeoftabstops(thenumberofspacestowhicheachtabcorresponds)isdeterminedbytheEditorpreference,“TabWidth.”
LineNumbers Raw(Chevron)Syntax
ScriptDebuggerHelp>Develop>Edit>ScriptWindow>ViewOptionsinaScriptWindow> TableofContents
Raw(Chevron)Syntax
ScriptDebuggerletsyouview,inascriptwindow,therawAppleeventcodescorrespondingtodictionaryterminologywithinacompiledscript.ThiscanhelpexplainterminologyclashesandotherunexpectedAppleScriptphenomena,andcangiveyouadeeperunderstandingoftheAppleeventsthatyourscriptisconstructingandsending.
ToviewrawAppleeventcodes:
ChooseView>ShowRaw(Chevron)Syntax.
Ifthemenuitemischecked,rawAppleeventcodesareshowing.
YoucanalsoseerawAppleeventcodesinthedictionary,inanoutliner,andintheeventlog.
Ifyou’reseeingrawAppleeventcodesunexpectedlyinanewlyopenedscript,itmaybebecausesomethinghasgonewrongwiththedecompilationprocess.
TabStops
ScriptDebuggerHelp>Develop>Edit>ScriptWindow> TableofContents
DefaultScriptWindowSizeandState
Theappearanceofanewemptyscriptwindowisuptoyou.Tosettheappearanceofnewscriptwindows:
1. Createanewscriptwindowandsetitupthewayyouwantit.Thismightincludesuchfeaturesas:
Size
Viewoptions
Configurationofpanesandinspectors,includingtheeventlog
2. ChooseWindow>SetDefaultScriptSize&State.
Fromnowon,newscriptwindowswillhavethesesamecharacteristics.
Note:Aspectsofthecontent(suchastext)ofascriptarenotpartofthedefaultscriptwindowappearance.Topreservescriptcontentforreuseinnewscripts,makeausertemplate.
ToreverttoScriptDebugger’sdefaultappearancefornewwindows:
ChooseWindow>ResetDefaultScriptSize&State.
ViewOptionsinaScriptWindow
ScriptDebuggerHelp>Develop>Edit> TableofContents
EditingandNavigation
ScriptDebuggerprovidestoolstomakeeditingandnavigatingyourscriptasfastandeffortlessaspossible.
Editing
ScriptDebuggerhelpsyoucreate,view,andselectblockstructureanddelimiterpairs.
ScriptDebuggerhelpsyoutype.ItcompletesAppleScripttermsforyou,plusyoucandefineyourowntextsubstitutions.Andthereareothermiscellaneoushelpfultypingandselectionfeatures.
Youcaneasilyinsertatellblock,oranycommoncontrolstructureorotherboilerplate,intoyourscript.YoucanalsoinsertcontentfromtheFinderoradictionarywindoworexplorerwindowtosavetyping.
Youcanpasteastringliteral,shiftindentationlevels,addorremovecomments,andinterchangetabandspacecharacters.
Ifallofthatisn’tenough,youcanedityourscriptwithanexternaleditor.
Navigation
ScriptDebuggerhaspowerfulfind-and-replacefeatures.
Youcansplitascriptwindow’seditingarea,soastoviewandeditmultipleregionsofyourscriptsimultaneously.
Youcanjumptoalinebynumber,ornavigatetoasectionofcodewithinyourscriptbymeansofthetableofcontentsmenu.
FurtherDetails:
BlockStructureDelimitersCodeCompletionTextSubstitutionAppleScriptObjCRefactoringMiscellaneousTypingandSelectionTellBlocksandTermsBlocksClippingsInsertingContentShiftCommentTabSplittingtheEditorFindGoToLineNavigateExternalEditor
ScriptWindow
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
BlockStructure
BlocksareacharacteristicandpervasivefeatureofAppleScript:atelllineisbalancedbyanendtellline(formingatellblock),arepeatlineisbalancedbyanendrepeatline(formingarepeatblock),andsoforth,andblocksarenestedinsideeachothertoformthelogicofyourscript.
ScriptDebuggermakesiteasytocreate,select,view,andcollapseyourcode’sblockstructure.
Creatingablockiseasy,becauseScriptDebuggerprovidesauto-closing:whenyoutypeReturnintheopeninglineofablock,Scriptdebuggerautomaticallygeneratestheendlineoftheblockforyou.
Selectingablockiseasy,thankstoScriptDebugger’sbalancecommand.
Viewingablockiseasy,thankstoblockshading.
Tocollapseablock,takeadvantageofScriptDebugger’scodefolding.(CodefoldingisnotavailableinLitemode.)
FurtherDetails:
Auto-ClosingBalanceCommandBlockShadingCodeFolding
Delimiters
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation>BlockStructure> TableofContents
Auto-Closing
Auto-closingisatextentryfeaturethatmakesiteasytocreateablockofAppleScriptcode.WhenyoutypeReturnintheopeninglineofablock,ScriptDebuggerautomaticallygeneratestheendlineoftheblockforyou.
Forexample,ifyoutyperepeatandpressReturnwithauto-closingturnedon,ScriptDebuggercreatesacorrespondingendline(whichwillcompiletoendrepeat),andpositionstheinsertionpointinbetween,readyforyoutoenterthecontentoftheblock.Thisworksalsoforlinesbeginningwithtell,on,script,if,try,using,considering,andignoring.ScriptDebugger’sauto-closingfeatureisintelligent;ifthereisalreadyacorrespondingendline,ScriptDebuggerwon’tcreateone.
Youcanturnonauto-closingingeneral,oruseitonsingleoccasions.Topickanauto-closingpolicy:
IntheEditorpreferences,checkoruncheck“Auto-closeAppleScriptblocks(endtell,etc.).”
Ifchecked,auto-closingisturnedoningeneral.Toturnauto-closingoffonasingleoccasion,holdControlasyoupressReturnattheendofablock-startingline.
Ifunchecked,auto-closingisturnedoffingeneral.Toturnauto-closingononasingleoccasion,holdControlasyoupressReturnattheendofablock-startingline.
BalanceCommand
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation>BlockStructure> TableofContents
BalanceCommand
TheBalancecommandmakesiteasytoselectablock:
ChooseEdit>Balance.
Or,chooseBalancefromthecontextualmenu.
EachtimeyouchooseBalance,ScriptDebuggerselectstheblockenclosingthecurrentselection.Thus,ifyouchooseBalancerepeatedly,youselecttheblockenclosingtheselection,thentheblockenclosingthatblock,thentheblockenclosingthatblock,andsoon.
TheBalancecommandselectsotherthingsbesidesblocks.Iftheinitialselectionisbetweenapairofdelimiters,thedelimitersandeverythingbetweenthemwillbeselectedfirst.Iftheinitialselectioniswithinacomment,thecommentwillbeselectedfirst.
Auto-Closing BlockShading
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation>BlockStructure> TableofContents
BlockShading
Toclarifytheblockstructureofyourscriptvisually,youcanhoverthemouseinthegutter(theareatotheleftofthescripttext).ScriptDebuggeroutlinesthenestedblockstructure,startingwiththeblocktotherightofthemouse,insuccessivelydarkershadesofgrey.
Toturnonblockstructureshading:
IntheEditorpreferences,checkoruncheck“Highlightblockswhenmousehoversingutter.”Ifchecked,blockstructureshadingisturnedon.
Whenthisfeatureisturnedon,youcanalsoselectablock.Todoso,clickthemouseinthegutterwhenyouseethenestedblockstructureoutlined.Clicksuccessivelytoselectthenextblockoutwards.ThisissimilartochoosingBalancerepeatedly.
Anotherwaytoseeblockstructureistousecodefolding.
BalanceCommand CodeFolding
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation>BlockStructure> TableofContents
CodeFolding
Codefoldingcallsattentiontotheblockstructureofyourcode,andalsopermitsyoutocollapseablock,hidingeverythingbutitsfirstline—thussavingspaceandhelpingyoutoviewandunderstandthelargerstructureofyourcode.
CodefoldingisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Codefoldingisadocument-levelfeature.Totogglecodefoldingonoroffforthecurrentscript:
ChooseView>ShowCodeFoldingsothatitischeckedorunchecked.
Ifcodefoldingisoff,blockscannotbecollapsed,andcodefoldingcommandsaredisabled.Therestofthediscussiononthispageassumesthatcodefoldingison.
Ablockcanbeexpandedorcollapsed:
Whenablockisexpanded,youseeallitscode.Thefirstlineoftheblockismarkedbyadown-pointingtriangle,andthecorrespondingendlineismarkedbyamatchingup-pointingtriangle.
Whenablockiscollapsed,youseeonlythefirstlineoftheblock,whichismarkedbyaright-pointingtriangle.Thehiddencontentisrepresentedbyanellipsisinacartouche.Thiscartoucheisselectable;ifyoucopyitandpasteitelsewhere,what’spastedisthecontentthatwashidden(everythingafterthefirstlineoftheblock,uptoandincludingthelastlineoftheblock).
Toseeanexpandedblock:
Hoverthemouseoveroneofthetriangles.Bothtrianglesarehighlighted,andyougetblockshading.
Tocollapseanexpandedblock:
Clickthedown-pointingtriangle.
Or,clicktheup-pointingtriangle.
Or,selectanywherewithintheblockandchooseEdit>CodeFolding>Fold.
Toexpandacollapsedblock:
Clicktheright-pointingtriangle.
Or,selectanywhereinthefirstlineoftheblockandchooseEdit>CodeFolding>Unfold.
Therearealsoseveralglobalfoldingcommands—theyaffecttheentirescript,andtheselectiondoesn’tmatter:
Edit>CodeFolding>UnfoldAll.Expandsallcollapsedblocks.
Edit>CodeFolding>Fold/UnfoldHandlers.Collapsesorexpandsallhandlers(blocksthatstartwithon).
Edit>CodeFolding>Fold/UnfoldBlockComments.Collapsesorexpandsallblockcomments(blocksthatstartwith(*).
BlockShading
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
Delimiters
Youcanenter,view,andselectdelimitersinpairs.Possibledelimiterpairsinclude:
Openingandclosingdouble-quotes""(somedelimitercommandsignorethese)
Leftandrightparentheses()
Leftandrightsquarebrackets[]
Leftandrightcurlybraces{}
Leftandrightchevrons«»
Leftandrightinlinecommentcharactersequences(**)
DelimiterEntry(Auto-Pairing)
Auto-pairingmeansthatwhenyoutypethefirstofapairofdelimiters,theseconddelimiterisautomaticallytypedforyou.
Whenyoutypeanopeningdelimiterwithauto-pairingon,theseconddelimiterappears,andtheinsertionpointispositionedbetweenthem,readyforyoutotypethedelimitedcontents.
Topickanauto-pairingpolicy:
IntheEditorpreferences,checkoruncheck“Auto-pairdelimiters([{""}]).”
Auto-pairingisintelligent:
Typeclosingdelimitertoskipclosingdelimiter:Whentheinsertionpointisbeforeaclosingdelimiterthatwasenteredautomaticallythroughauto-pairing,ifyoutypetheclosingdelimiter,ScriptDebuggerknowsthatthisisthesameclosingdelimiterthatisalreadypresent,andskipspasttheclosingdelimiter,positioningtheinsertionpointafterit.
Surroundtheselection:Optionally,whentextisselected,ifyoutypeanopeningdelimiterwithauto-pairingon,theselectedtextisnotreplaced;instead,theselectedtextissurroundedwithopeningandclosingdelimiters.Thisfeatureisgovernedbyapreference:
IntheEditorpreferences,checkoruncheck“Wrapselectionwithdelimiters.”
DelimiterCheckingAsYouType(Auto-hilite)
Auto-hilitemeansthatwhenyoutypethesecondofapairofdelimiters,thefirstdelimiterismomentarilyhighlighted.Thisconfirmsthatyou’rebalancingdelimitersasintended.
Ifthereisnopriormatchingfirstdelimiter,ScriptDebuggerbeeps.Thisalertsyouthattheclosingdelimiterisunbalanced.
Topickanauto-hilitepolicy:
IntheEditorpreferences,checkoruncheck“Auto-hiliteopening([{whentypingclosing}]).”
Usetheslidertosethowmuchdelaythereshouldbebeforetheopeningdelimiterishighlighted.
Check“Scrollifnecessary”checkboxifyouwantScriptDebuggertoscrollbackwardsmomentarily,ifneeded,torevealabalancingopeningdelimiterthat’snotcurrentlyvisible.
DelimiterSelection(Balance)
Balancemeansthatyouselecteverythingwithinapairofdelimiters.ScriptDebuggerstartswiththecurrentselectionorinsertionpointandlooksoutwarduntilitreachesapairofbalanceddelimiters.Tobalance:
ChooseEdit>Balance.
Or,chooseBalancefromthecontextualmenu.
Todeterminewhetherbalancingshouldincorporatethedelimitersthemselvesintheselection:
IntheEditorpreferences,checkoruncheck“Balanceincludesenclosing([{}])delimiters.”
Ifchecked,Balanceselectseverythingincludingthesurroundingdelimiters.
Ifunchecked,Balanceselectseverythingwithinthesurroundingdelimiters.
Balanceconsidersacommenttobeadelimitedthing.IfyouchooseBalancewhentheselectioniswithinasingle-lineormulti-line
comment,thecommentwillbeselected.
Balanceconsidersablocktobeadelimitedthing.IfyouchooseBalancewhentheselectioniswithinacodeblock,theblockwillbeselected.
Balancerepeatedlytokeepselectingoutwards.
Balanceisthesamefeatureusedforblockselection.
BlockStructure CodeCompletion
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
CodeCompletion
CodecompletionmeansthatyoutypethestartofanAppleScripttermandtherestofthetermistypedforyou.
Tosummoncodecompletion:
PressEscorF5.Alistofpossiblecompletionsappears.
ThisisessentiallythesameastheCompleteorauto-suggestionfunctionalitythatappearsgenerallyinCocoaapplicationssuchasTextEdit,Pages,andsoon.ScriptDebuggercreatesalistofpossiblecompletions,basedon:
Identifiersinthescriptitself(suchashandlernames)
AppleScriptterminology
Scriptingadditionterminology
Terminologyoftheapplicationtargetedbythecurrenttellcontext
Terminologyimportedbyausescriptstatement
Cocoatermsimportedbyauseframeworkstatement
Certaincodecompletionshelpyouconstructatellortermstargetorausestatement:
Codecompletionbetweenthequotesinapp""orapplication""producesalistofrunning,recent,andfavoriteapplications.Choosingfromthelistentersthenameoftheapplication.(Ifyourtextsaysappid""orapplicationid"",choosingfromthelistenterstheapplication’sid.)
Codecompletionbetweenthequotesinscript""producesalistofavailablelibraryscripts.
Codecompletionbetweenthequotesinframework""producesalistofframeworkscommonlytargetedbyAppleScriptObjC.
Toacceptacompletion:
Navigatethelistwitharrowkeystoselectthecompletion,andpressReturn.
Or,double-clickthedesiredcompletion.
Tocancelcompletion:
PressEscorF5.
Somecompletionsinvolveplaceholders,similartoclippings.Forexample,ifacodecompletionisahandlercall,andifthathandlertakesparameters,theparametersareplaceholders.
CodeCompletionKeyboardShortcuts
Whileatermisundergoingcodecompletion,certainspecialkeyboardshortcutsbecomeavailable.Thisisbestexplainedbyanexample:
Intheabovescreenshot,wehavetypedstringByAfollowedbyEsctogetcodecompletion.Atthismoment:
Pressingleftarrowordeletereducestheoriginaltypingbyonecharacter.If,startingfromthescreenshot,wepressleftarrow,wearenowcompletingstringBy,andlotsofadditionalcompletionsappear,suchasstringByDeletingLastPathComponent.
Pressingrightarrowincreasestheoriginaltypingbyonecharacter.If,havingpressedleftarrow,wepressrightarrow,wearenowcompletingstringByAonceagain.
PressingTabincreasestheoriginaltypingbyonecamelCasedwordortothenextinternalunderscore.If,startingfromthescreenshot,wepressTab,wearenowcompletingstringByAppending,andourchoiceofcompletionsisreducedtofour.
AppleScriptObjCCompletions
AppleScriptObjCcompletionsareofferedintelligently,basedon:
useframeworkstatements.Completionswillbeofferedonlyforframeworksactuallyused.
AuseAppleScriptversionstatement.ThesystemimpliedbytheAppleScriptversionisthelatestversionforwhichcompletionswillbeoffered.
Context.Ithelpsifyouusethepossessivesyntaxillustratedintheexamples.
Terminologyclash.Pipesareinsertedwhereclashwouldotherwiseoccur.
Atarget,suchascurrentapplication'sorits,isinsertedasneeded;yoursettingsdeterminethedetails.
EachAppleScriptObjCcompletionofferedisaccompaniedbyanotationstatingitstype.Theseare:
Types
[class] Aclassname
[const] Aconstant
[=#] Anenumnumericallyequivalentto#
[ƒtype] Afunctionreturningtype
[+type] Aclassmethodreturningtype
[-type] Aninstancemethodreturningtype
Delimiters TextSubstitution
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
TextSubstitution
Youcandefineabbreviationswithsubstitutions;youtypeanabbreviationanditisreplacedbythesubstitution.Replacementoccursautomaticallywhenyoutypeanonwordcharacter(punctuationorline-ending)afteranabbreviation.
Thiscanbeaconvenientwaytoenterboilerplatetext,commonlyusedcontrolstructuresandcommands,orcharactersthataredifficulttotypedirectly;itcanalsobeaformofautomaticspellingcorrection.
Toenableordisabletextsubstitution:
IntheTextSubstitutionpreferences,checkoruncheck“Enabled”.
Tomanagethelistofabbreviationsandsubstitutions:
UsetheTextSubstitutionpreferences:
Clickthe+buttontocreateanewsubstitution.
Clickthe-buttontodeleteaselectedsubstitution.
Double-clickintheReplaceorWithcolumntoedittext.
Todisableanindividualsubstitutioneveniftextsubstitutionsareenabled,unchecktheOncheckbox.
Textsubstitutionsusethesameexpansiontagsasclippings.Thus,thetextinsertedthroughatextsubstitutioncancontainplaceholders,ofwhichonemayinitiallybeselected.
Youcanalsoexporttheentiresetoftextsubstitutions(in.plistformat)orimportapreviouslyexportedsetoftextsubstitutions.
CodeCompletion AppleScriptObjCRefactoring
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
AppleScriptObjCRefactoring
FourEditmenuitemshelpkeepyourAppleScriptObjCcodeneat.
TheseAppleScriptObjCcommandsareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Tounderstandwhattheydo,let’stakeanexample.Considerthiscode:
setsstocurrentapplication'sNSString'sstringWithString:ssetregextocurrentapplication'sNSRegularExpressionSearch
ThatcodeillustratesanessentialproblemwithAppleScriptObjCcode:everythingmustbeexplicitlytargetedatthecurrentapplication.AppleScriptObjCrefactoringreorganizesthatsortofcodesothatCocoanameslikeNSStringandNSRegularExpressionSearcharedefinedaspropertiesofyourscript.Yourcodecanthenusethebarepropertynamesasashorthand.
Thus,giventheabovecode,ifyouchooseEdit>AppleScriptObjective-C>MigratetoProperties,yourcodeisrefactoredintotwopieces.First,somepropertydefinitionsareinsertedatthestartofthescript:
--classes,constants,andenumsusedpropertyNSRegularExpressionSearch:areferenceto1024propertyNSString:areferencetocurrentapplication'sNSString
Then,thecodeitselfhascurrentapplication'sstrippedout,sothattheCocoanamesbecomethenamesofthescriptproperties:
setsstoNSString'sstringWithString:ssetregextoNSRegularExpressionSearch
Theextraworkupfront—theuseofpropertydeclarationsearlyinyourcode,alongwiththeareferencetolocution—streamlinesyouruseofCocoatermslater,reducesoverheadatruntime,andavoidssomeotherundesirablesideeffects.
TherearefourEdit>AppleScriptObjChierarchicalmenuitemsconnectedwithrefactoring:
Edit>AppleScriptObjC>MigratetoProperties
Performstherefactoringdescribedabovefortheentirescript.
Edit>AppleScriptObjC>MigratetoPropertiesinSelection
Performstherefactoringdescribedaboveforjusttheselectedcode.
Edit>AppleScriptObjC>UsePropertiesforCocoaTerms
Ifchecked,thenwhencodecompletionoraclippinginsertsCocoaterms,itperformsrefactoringatthesametime.AnEditorpreference,“UsepropertiesforCocoatermsincompletion,clippings”,governsthisbehavioringeneral;thismenuitemletsyouoverridethatsettingforanindividualscript.
Edit>AppleScriptObjC>CopyasStandaloneCode
Copiestheselectedmaterialtotheclipboard.Ifthatmaterialisrefactoredasdescribedabove,theclipboardcopyisunrefactored.Thus,forexample,ifyouweretocopysetsstoNSString'sstringWithString:sasstandalonecode,itwouldbecopiedassetsstocurrentapplication'sNSString'sstringWithString:s,suitableforpastingintoadifferentscript(andthenrefactoringthere,ifdesired).
Refactoringrequiresthatthescriptbecompiled,sotheMigratetoPropertiesinSelectionandCopyasStandaloneCodecommandswillbedisabledifthescriptneedscompilation.IfyouchoosetheMigratetoPropertiescommandwithanuncompiledscript,adialogwillaskifyouwantthescripttobecompiledfirst.
TextSubstitution MiscellaneousTypingandSelection
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
MiscellaneousTypingandSelection
HerearesomemiscellaneoustypingandselectionfeaturesofScriptDebugger.
Tonavigatewiththekeyboard,ScriptDebuggersupportsafullrepertoireofkeyboardnavigationshortcuts:
RightArrowandLeftArrownavigatebycharacter.
Option-RightArrowandOption-LeftArrownavigatebyword.
Command-RightArrowandCommand-LeftArrownavigatetothetwoendsofthecurrentline.
Option-UpArrowandOption-DownArrownavigatealineatatime.
Command-UpArrowandCommand-DownArrownavigatetothestartandendofthescript.
Toselectwiththekeyboard:
AddShifttotheabovekeyboardnavigationshortcuts.
Toselectaline:
Triple-clickontheline.Youcantriple-click-dragtoselectastretchoflines.
Clicktotheleftoftheline.Justtotherightofthegutterisanarrowareawherethisclickworkstoselectaline.Youcanclick-dragtoselectastretchoflines.
ClickorselectanywherewithinthelineandthentypeShift-Command-RightArrow,Shift-Command-LeftArrow.YoucanthenuseShift-UpArroworShift-DownArrowtoselectastretchoflines.
Tostartanewline:
PressCommand-Return.Nomatterwheretheinsertionpointorselectionisinthecurrentline,thecurrentlinewillbeabandoned,andanewlinewillbeinsertedbelowthecurrentline,withtheinsertionpointatitsstart,readytotype.
ToappendanAppleScriptline-continuationcharactertothecurrentlineatthesametime,pressCommand-Option-Return.
Thisfeaturemaybecombinedwithauto-closing;forexample,ifyoustartinthemiddleofatelllineandpressCommand-Return,thenifthereisnocorrespondingendline,theendlinewillbecreatedifauto-closingisturnedon.
AppleScriptObjCRefactoring TellBlocksandTermsBlocks
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
TellBlocksandTermsBlocks
Therearemanywaystocreateatellblocktargetingaparticularapplication.ThisisvaluablebecausescriptinganapplicationwithatellblockissocommonwhenusingAppleScript.
Moreover,youcancreateatellblockcontainingareferencetoanobjectwithinthetargetedapplication,orcontainingacommandorfunctiontemplate.
Atellblockisakindofautomaticallygeneratedclipping,andmayinvolveplaceholders.
Somewaysofcreatingatellblockarealsowaysofcreatingausingtermsfromblock.
Usecodecompletion,inascript:
Typetellapp""ortellapplication""and,withthecursorbetweenthequotes,pressEsc.Thisproducesapop-upmenuofrunning,recent,andfavoriteapplicationstochoosefrom.
Usetextsubstitution,inascript:
Typeta(meaning“tellapplication”)followedbyaspace.Atellblockiscreated,andtheapplicationnameisapickerplaceholder:youcantypethenameoftheapplication,orsummonapop-upmenuofrunning,recent,andfavoriteapplications.
Inascriptwindow’smenus:
ChooseEdit>PasteTell.
Or,Control-clickandchoosePasteTellfromthecontextualmenu.
ThehierarchicalPasteTellmenucontainsthesameshortenedversionofthedictionarieslist(withouttheAllcategory)thatappearsintheFile>OpenDictionarymenu.Inthemenu:
Chooseanapplicationtoinsertatellblocktargetingthatapplication.
Moreover,forrunningapplications,eachapplicationinthePasteTellmenuhasitsownhierarchicalmenuthatletsyounavigateitsobjecthierarchy,muchasifthismenuweretheoutlinerofanexplorer.Chooseanobjecttoinsertatellblocktargetingthatapplicationandreferringtothatobject.
HoldOptiontoinsertthetellblockintoanewscript.
Inascriptwindow’sdictionariesinspector:
SelectanapplicationandclickPasteTellorPasteUsing.Alternatively,choosePasteTellXXXorPasteUsingTermsFromXXXfromthecontextualmenu.
Or,clickopenthetrianglenexttoanapplication’snametoseealistofthatapplication’scommandsandfunctions.SelectacommandorfunctionandclickPasteTell.You’llgetatellblockwithacommandtemplate.
HoldOptiontopasteintoanewscript.
Inascriptwindow’stellcontextinspector:
SelectanobjectreferenceandclickPasteTell.
You’llgetatellblockreferringtothatobject.
Inadictionarywindow:
ChooseDictionary>PasteTell.
Or,clickPasteTellinthedictionarywindow’stoolbar.
Or,Control-clickinthedictionarieslistandchoosePasteTellXXX(orPasteUsingTermsFromXXX).
Or,control-clickintheterminologylistandchoosePasteTellXXX(ordrag-and-dropfromtheterminologylistintoyourscript).
Ifthefocusisonacommandorevent,you’llgetatellblockwithacommandtemplate.HoldOptiontopasteintoanewscript.
Inadictionarywindow’sexplorer:
SelectanobjectreferenceandclickPasteTellinthetoolbar.
Or,chooseDictionary>PasteTellXXX.
You’llgetatellblockreferringtothatobject.HoldOptiontopasteintoanewscript.
Inanoutliner(includingtheresultpane,thedictionarywindow’sexplorer,andsoon):
Control-clickonalineoftheoutlinerandchoosePasteTellfromthecontextualmenu(ordrag-and-dropalineoftheoutlinerintoyourscript).
You’llgetatellblockreferringtothatobject.HoldOptiontopasteintoanewscript.
IntheFinder:
Drag-and-dropanapplicationintoyourscriptwindow.Adialogappearsaskingwhatyouwanttodo.Oneoptionistopasteatellblocktargetingthatapplication.
(Alternatively,drag-and-dropanapplication’snamefromthedictionariesinspectorintoyourscriptwindow.Or,drag-and-dropfromthedictionarieslistinadictionarywindowintoyourscriptwindow.)
MiscellaneousTypingandSelection Clippings
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
Clippings
Clippingsarebitsofboilerplatetextthatyoucaninsertintoyourcode.ClippingsareaccessedfromwithinScriptDebuggerintwomainplaces:
TheClippingsmenu( ).
Theclippingsinspector.ItisintheInspectorstabofascriptwindow.Toseetheclippingsinspector:
ChooseView>InspectorsTab.
Or,clickthethethirdShowbuttoninthescriptwindowtoolbar.
Youcaninsertaclippingintoyourscriptinanyofthefollowingways:
ChooseitfromtheClippingsmenu.
Or,control-clickinascriptwindow’stextareaandchoosePasteClippingfromthecontextualmenu.ThehierarchicalmenucontainsthesameclippingsastheClippingsmenu.
Or,intheclippingsinspector,double-clickaclipping.
Or,intheclippingsinspector,selectaclippingandclickPasteClipping.
Searchingintheclippingsinspectorsearchesboththetitlesandthecontentsofclippings.
Aclippingcanwrapthecurrentselection.Thisallowsyoutoincorporateexistingtextinyourscriptintotheheartoftheclippingastheclippingisinserted.Forexample,youmightrealizethatpartofyourscriptneedstoberepeated,soyou’dliketowrapitinarepeatblock.Selectthetextandthenchoosearepeatblockclipping,suchas“repeatntimes”.Arepeatblockisinserted,wrappedaroundthetextthatyouselected.
Aclippingmayinvolveplaceholders.
Youcancreateyourownclippings.Yourclippingswillappearatthetopoftheclippingsinspectorandmenu,followedbyaseparator.TheEditClippingbuttonatthetopoftheclippingsinspectorwillbeenabledifyouselectoneofyourownclippings.
FurtherDetails:
PlaceholdersHowClippingsWork
TellBlocksandTermsBlocks InsertingContent
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation>Clippings> TableofContents
Placeholders
Aclippingcanincludeplaceholders.
Aplaceholderisdisplayed(inanuncompiledscript)asastretchoftextinaroundedrectangle.Theideaisthatyoucaneasilyselectanentireplaceholder,andtypeorpastetoreplaceitwiththedesiredtext.
Toselectaplaceholder:
PressTab.EachtimeyoupressTab,theselectioncyclestothenextplaceholder.(Alternatively,pressShift-Tabtocycleinreverseorder.)
Or,chooseEdit>GotoNextPlaceholderorEdit>GotoPreviousPlaceholder.
Or,clickontheplaceholder.Theentireplaceholderisselected.
Placeholdersthatyoudon’teditarereplacedbynormaltextwhenyoucompileyourscript.Or,toacceptaplaceholder,replacingitwithnormaltextimmediately,selecttheplaceholderand:
PressReturnorEsc.
Or,chooseEdit>CommitPlaceholder.
Placeholdersarealsousedbycodecompletionandbygeneratedtellblocks.
Specialplaceholders
Someplaceholdershaveaspecialappearance.
Aplaceholderwithadown-pointingchevronisapicker.Itproducesapop-upmenuofitemsthatyoucanchoosefromtoreplacetheplaceholder.Forexample,the“application”placeholderhereisapicker;itspop-upmenuisthesameasthelistofrunning,recent,andfavoriteapplicationsthatappearselsewhere:
Topopupapickerplaceholder’smenu:
SelectthepickerplaceholderandpressReturnorEsc.
Or,clickthepickerplaceholder.
Aplaceholderwithalinkisalinkedplaceholder.Ifyouselectitandinserttextinitsplace,thattextalsoreplacesanotherplaceholderwiththesamename(andalink):
HowClippingsWork
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation>Clippings> TableofContents
HowClippingsWork
ScriptDebuggerprovidesclippingscorrespondingtoallcommonlyusedAppleScriptcontrolstructures,andyoucanaddyourownclippings.Clippingsaretextfilesin~/Library/ApplicationSupport/ScriptDebugger7/Clippings;youarefreetoaddtextfileshere.
ClippingNamesandMenuOrder
Ifyouhavenotaddedanyclippingsofyourown,ScriptDebugger’sdefaultsetofclippingswillappearinalphabeticalorderintheClippingsmenuandclippingsinspector.Ifyouhaveaddedyourownclippings,thesewillappearsortedatthetop,separatedfromthedefaultsetbyaseparator.
Thenameofaclippingfile(strippedofitsfileextensionsuffix)isthenameoftheclipping.Youcanmodifytheorderinwhichyourownclippingsappearaccordingtothefollowingrules:
Afilewillappearasamenuitem.Afolderwillappearasahierarchicalmenu,andthefilesinsideitwillbeitsmenuitems.Thenameofafile(orfolder)isthenamethatwillappearinthemenu,exceptthatcertainnamesorpart-namesarehiddenandusedfordeterminingtheorderofthemenu,asfollows:
Ifanamestartswiththeprefix#),where#isawholenumberofanylength,thatnumberdeterminesthepositionofthisiteminthemenuandtheprefixdoesnotappearinthemenuitem’sname.
Aname#)-***willappearasamenuseparator,againwithitsorderdeterminedbythewholenumber#.
ClippingsActions
Toeditaclipping:
ChooseitfromtheClippingsmenu,ordouble-clickitintheclippingsinspector,whileholdingdowntheOptionkey.
Or,selecttheclippingintheclippingsinspectorandclickEditClipping.
TorevealaclippingfileintheFinder:
ChooseitfromtheClippingsmenu,ordouble-clickitintheclippingsinspector,whileholdingdowntheShiftkey.
Or,intheclippingsinspector,selecttheclippingandchooseRevealinFinderfromthecontextualmenu.
ExpansionTags
Aclipping’stextispastedliterallyintoyourscript,exceptforthefollowingexpansiontagswhichareinterpretedintelligently:
[[select:text]]Displaystextandalsoselectsit.
[[linked-template:text]]Displaystextasaplaceholder.Ifthesametextisusedasaplaceholdermultipletimes,theplaceholdersarelinked—editingoneofthemeditsallofthemsimultaneously.
[[unique-template:text]]orsimply[[template:text]]Displaystextasaplaceholder.Ifthesametextisusedasaplaceholdermultipletimes,theplaceholdersarenotlinked.
Thetemplatetextapplication,applicationid,applicationhfs,applicationposix,library,andframeworkisinterpretedspecially:itgeneratesapickerplaceholder,producingapop-upmenuofapplications,libraryscripts,orframeworksrespectively.Thefourapplicationtemplatesdifferinwhatisenteredwhentheuserchoosesfromthepop-upmenu—theapplication’sname,id,HFSpath,orPOSIXpath,respectively.
[[user]]Displaystheuser’sfullname.
[[name]]Asynonymfor[[user]].
[[account]]Displaystheuser’sshortname(seenwhenusingtheuserscommandintheTerminal).
[[copyright]]DisplaysthecopyrightstringfromtheGeneralpreferencepane.
[[organization]](or[[org]])Displaystheuser’scompanyname,asshownintheCompanyfieldintheuser’sContactsentry.(Ifthatfieldisblank,displays“MyCompanyName”asaplaceholder.)
[[date]]Displaysthedateintheformatmm/dd/yyhh:mm:ss.Foralternateformats,youcanuse[[short-date]],[[long-date]],[[short-time]],and[[long-time]],whichareconfiguredinyourSystemPreferences(Language&Region>Advanced).Fortheyearalone,use[[year]].Forultimateflexibility,youcanspecifyacustomdateformatbysaying[[date:format]]wheretheformatisanunquotedstrftime()formatstring.
[[selected-lines:defaulttext]]Displaysthecompletelinescontainingthescript’scurrentselection.Ifthecurrentselectionisjustaninsertionpointinanemptyline,defaulttextisused,andisdisplayedasaplaceholder.
[[selection:defaulttext]]Displaysthescript’scurrentselection.Ifthecurrentselectionisjustaninsertionpoint,defaulttextisused,andisdisplayedasaplaceholder.
[[VARNAME]]DisplaysthevalueoftheVARNAMEenvironmentvariable.So,forexample,[[SHELL]]wouldbeexpandedtosomethinglike/bin/bash.Anythingindoublebracketsthatdoesn’tmatchoneoftheprecedingtagtypesistakentobethenameofanenvironmentvariable.Ifthereisnomatchingenvironmentvariablename,thetagisleftunchanged;forexample,[[howdy]]becomes[ [howdy]].
ApplescriptDirective
Aspecialdirectiveisdesignedtoinsertausestatementforscriptlibraries.Thiscanbeinoneoftwoforms:
[[*library:libraryname]]Ensuresthatausestatementforthislibraryispresentatthestartofthescript.
[[library:libraryvariable:libraryversion:libraryname]]Ensuresthatadetailedusestatementforthislibraryispresentatthestartofthescript.Bothlibraryvariableandlibraryversioncanbeemptystringstoavoidtheparameterbeingadded,so[[*library:libraryname]]and[[*library:::libraryname]]areidentical.Wherethereisanexistingusestatementforthelibrary,ifthereisaconflictofvariablenamesorthenewversionnumberishigherthanonealreadydefined,aseconduserstatementwillbeadded.Thiswillresultinanerroratcompiletime,alertingyoutotheconflict.Ifthereisnoissue,thespecifiedparameterswillbeaddedtotheexistingstatementwherenecessary.
ApplescriptObjCDirectives
AnumberofdirectivesdevisedforuseinAppleScriptObjCclippingsresultinspecialbehavior.ThesedirectivesareafeatureofthefullversionofScriptDebugger;theyareignoredinLitemode.
Youmayneverusethesedirectives,butyoumightseethemintheclippingsandwonderwhattheymean,soheretheyare:
[[*framework:frameworkname]]Ensuresthatausestatementforthisframeworkispresentatthestartofthescript.
[[template:trueOrFalse]]Displaysapickerplaceholderwhichpresentsachoiceoftrueorfalse.
[[template:missingValueOrReference]]Displaysapickerplaceholderwhichpresentsachoiceofmissingvalueorreference.
[[*piped:someterm]]Displayssometerm,checkingforterminologyclashandsurroundingsometermwithpipesifneededtoavoidtheclash.
[[*class:classname]]Displaysclassname,checkingforterminologyclash,andaddingcodesothatitistreatedasanAppleScriptObjCclassname.Forexample:currentapplication'sNSString.
[[*constant:constantname]]Displaysconstantname,checkingforterminologyclash,andaddingcodesothatitistreatedasanAppleScriptObjCconstantname.
[[*enum:value:enumname]]Displaysenumname,checkingforterminologyclash,andaddingcodesothatitistreatedasanAppleScriptObjCenumname.Thevalueisoptional;ifpresent,itisaninteger,andisusedasthevalueoftheenumeration.
TheprecisebehaviorofthelastthreedirectivesdependsontheEditorpreferencesettingfor“UsepropertiesforCocoaterms,”possiblyoverriddenbyEdit>AppleScriptObjC>UsepropertiesforCocoaterms.Ifnotchecked,currentapplicationisinserteddirectly.Ifchecked,apropertydeclarationisinsertednearthestartofthescript,suchthatthebaretermissufficientinitscontext.
Placeholders
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
InsertingContent
Therearemanyconvenientshortcutsforinsertingcontentintoyourscriptfromelsewhere.Here’sasummary.
Youcancreateatellblockinmanydifferentways,includingatellblockcontainingacommandtemplateoranobjectreference.
Youcantypeanabbreviationcorrespondingtoatextsubstitution.
YoucantypethestartofanAppleScripttermandletbecompletedautomatically.
Youcantakeuseauto-closingtoenterendlinesautomatically,andauto-pairingtoenterclosingdelimitersautomatically.
Youcanpasteaclippingtoinsertboilerplate,suchasanAppleScriptcontrolstructure.
FromtheFinder,drag-and-dropafileorfolderintoyourscript.Adialogappearsaskingwhatyouwanttodo.
Ifwhatyoudraggedisanapplication,oneoptionistoinsertatellblocktargetingthatapplication.
Youcaninsertthename,alias,orpathname(POSIXorMacintosh-style)ofthedroppeditems.Multipledroppeditemsarecombinedintoalist.
Youcaninsertanobjectspecifier(reference)suitableforuseinatellblocktargetingtheFinder.
Ifwhatyoudraggedisatextfile,youcaninsertitscontents.
Inadictionarywindow,inadditiontothevariousPasteTellcommands,youcanalsousedrag-and-drop:
Drag-and-dropfromthedictionarieslistattheleftofthedictionarywindowintoascript.TheeffectisthesameasdraggingtheapplicationfromtheFinder.
Drag-and-dropfromtheterminologylistintoascript.TheeffectisthesameaschoosingPasteTell.
Inanexplorer’soutliner:
Drag-and-dropalineoftheoutlineintoyourscript.You’llgetapastetellreferringtothedraggedobject.Alternatively,selecttheline,chooseEdit>Copy,andpasteintoyourscript.
Ifwhatyouwanttoinsertintoyourscriptisthevalueofaproperty,Control-clickonthepropertyandchooseCopyValue(orholdShiftandchooseEdit>Copy),andthenpasteintoyourscript.
Clippings Shift
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
Shift
Youcanremoveoraddalevelofindentationtotheselectedlines.Tochangetheindentationlevel:
SelectsometextandchooseEdit>ShiftLeftorEdit>ShiftRight.(YoucanalsoaddShiftLeftandShiftRightbuttonstothescriptwindow’stoolbar.)
Theselectionwillbeexpandedtoconsistofcompletelines,andatabcharacterwillberemovedfromoraddedtothestartofeachselectedline.
AppleScriptwillperformitsownindentationwhenthescriptiscompiled,whichmayalterthenumberoftabcharactersatthestartofaline(exceptinsideamultilinestringliteral).
SeealsoonShowInvisibles,ShowSpaces,andShowTabStops.
InsertingContent Comment
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
Comment
Youcanuseshortcutstocommentoruncommentastretchofcode.
Tocommentoutastretchofcode:
SelectthecodeandchooseEdit>Comment.OrchooseCommentfromthecontextualmenu.
ScriptDebuggerwillextendtheselectiontoconsistofcompletelines,andwilltheninsertasingle-linecommentcharacteratthestartofeachofthoselines.
Touncommentastretchofcomments:
SelectsomecodeandchooseEdit>Uncomment.OrchooseUncommentfromthecontextualmenu.
ScriptDebuggerwillextendtheselectiontoconsistofcompletelines,andwillthenremoveasingle-linecommentcharacterfromthestartofeachofthoselines,ifthereisone.(Ifthereisn’tone,that’sfine.Thelineisleftunaltered.)
(YoucanalsoaddCommentandUncommentbuttonstothescriptwindow’stoolbar.)
WhydoesScriptDebuggerusesingle-linecommentsratherthansurroundingtheselectedtextwithblockcommentdelimiters,(*likethis*)?Onereasonisthatblockcommentsarefragile.Anunbalanceddouble-quotewithinblockcommentdelimiterswillkeepyourscriptfromcompiling.Single-linecommentsaresimpler.Infact,withScriptDebugger,multiplesingle-linecommentsareeasiertodealwiththanblockcomments.Toinsertblockcommentdelimiters,usetheBlockCommentclipping.
Asingle-linecommentcharactercanbeeither“--”or“#”.TodeterminewhichisinsertedbytheCommentcommand,andtosetthenumberofspacesthatshouldfollowthecommentcharacter,usetheEditorpreference,“Edit>CommentInserts.”
Shift Tab
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
Tab
Youcanconverttabstospacesandviceversa.
Todoso:
SelectsometextandchooseEdit>EntaborEdit>Detab.(YoucanalsoaddEntabandDetabbuttonstothescriptwindow’stoolbar.)
Theselectionwillbeexpandedtoconsistofcompletelines,andtheindentationwhitespaceatthestartofthoselineswillbeconvertedtotabsorspacesrespectively.
Thisisusefulparticularlywhenascriptmustbepastedintosomeotherenvironment,wherespacesarebetterinterpretedthantabcharacters.Forexample,beforecopyingandpastingascriptintoanemailmessageorawebpage,youmightSelectAllandthenDetab.
Thesizeoftabstops(thenumberofspacestowhicheachtabcorresponds)isdeterminedbytheEditorpreference,“TabWidth.”
SeealsoonShowInvisibles,ShowSpaces,andShowTabStops.
Comment SplittingtheEditor
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
SplittingtheEditor
Youcansplitthescriptwindowtextareaintomultiplepanes.Thiscanbehelpfulinalongscript,lettingyouviewandeditmorethanoneareaofyourscriptsimultaneously.
Youcansplitthetextareaverticallyorhorizontally—andyoucanspliteachresultingpaneverticallyorhorizontally.Eachpanecanbescrolledtodisplayadifferentregionofthescript.
Tosplitascriptwindoworpanevertically:
Clicktheverticalspliticon( )intheverticalscrollbar.
Or,chooseEdit>SplitEditorVertically.
Or,chooseSplitEditorVerticallyfromthecontextualmenu.
Tosplitascriptwindoworpanehorizontally:
Clickthehorizontalspliticon( )inthehorizontalscrollbar.
Or,chooseEdit>SplitEditorHorizontally.
Or,chooseSplitEditorHorizontallyfromthecontextualmenu.
Toresizeapane:
Dragthedividerlinebetweenpanes.
Tocloseapane:
Clickitscloseicon( )atthelowerrightcornerofthepane.
Or,chooseEdit>CloseSplitView.
Or,chooseCloseSplitViewfromthecontextualmenu.
Tocloseallpanes:
Option-clickanycloseicon( ).
Or,holdOptionandchooseCloseAllSplitViews(fromtheEditmenuorthecontextualmenu).
Whatshouldhappenwhenyouchangeaviewsetting(suchaslinewrappingorvisibilityoftabstops)inasplitpane?Shouldothersplitpaneschangetomatch,orshouldtheirviewsettingsremainindependent?Todeterminethis,usetheEditorpreference,“Synchronizesplit-viewappearance”:
Ifchecked,thenwhenyouchangeaviewsettinginonesplitpane,othersplitpanesofthesamewindowwillchangethesamesettingtomatch.Ifunchecked,thenachangetoaviewsettingappliestojustonesplitpane.
HoldOptionasyouchangeaviewsettingtoreversethispreferenceononeoccasion.
Whenyouselecttextinonepane,shouldthesametextbeselectedinallotherpanes?Todeterminethis,usetheEditorpreference,“Synchronizesplit-viewselection.”
Tab Find
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
Find
Tosearch(andreplace)withinascript,you’llusethefindbarandtheSearchmenu.
Tosummonthefindbar:
ChooseSearch>Find.
Todismissthefindbar:
ClickDoneinthefindbar.
Or,pressEsc.
Toconfigureasearchinthefindbar,usethecheckboxes:
RegEx.Ifchecked,thesearchstring(andreplacestring)willbeinterpretedasaregularexpression.ScriptDebuggerusestheICUflavorofregularexpressionsyntax(itisbasedonCocoa'sNSRegularExpressionclass).
Bydefault,.doesn’tmatchthereturncharacterattheendofaline;youcanreversethiswiththe(?s)flag.
MatchWords.Ifchecked,thesearchstringissoughtbetweenwordboundaries.
IgnoreCase.Ifchecked,thesearchiscase-insensitive.
Wrap.Ifchecked,successiveFindAgaincommandslooparoundthedocument.Ifunchecked,ReplaceAllaffectstextonlyafterthestartofthecurrentselection.
Toperformasearch:
Thesearchisinitiallyperformedautomaticallyasyoueditthesearchstring.
Tosearchforwardorbackward,chooseSearch>FindAgain(Backwards),orclickthearrowbuttonsinthefindbar.
TheWrapcheckboxaffectsthebehaviorofthiscommand.
Toperformasearch-and-replace:
Clickthe&ReplacebuttontorevealthereplacestringandReplacebuttons.
ClickaReplacebuttonorchooseaReplacecommandfromtheSearchmenu.
TheWrapcheckboxaffectsthebehaviorofReplaceAll(andReplace&Find).
Youcanuseselectedtextasthesearchorreplaceterm;chooseSearch>FindSelection(Backwards)orUseSelectionforFind/Replace.
Torecallarecentsearch,clickthemagnifying-glassiconinthesearchfield.
SplittingtheEditor GoToLine
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
GoToLine
Youcanjumptoalinebynumber.Todoso:
ChooseEdit>GoToLineandenteralinenumberinthedialog.
(Thenumberthatappearswhenyousummonthisdialogisthenumberofthelinewhereyoucurrentlyare.)
Toworkmoreeasilywithlinenumbers,youcanelecttoshowlinenumbersinyourscript.Also,thenavigationbar(atthetopright,abovethetextareainthescriptwindow)alwaysshowsthecurrentlinenumber.Andthere’sanEditorpreference,“Shownavigationbarlocationwhenscrolling,”thatcauseslinenumberstobeshowninatooltipwhileyouscroll.
There’salsoa“tableofcontents”menuforjumpingtoahandlerorothertop-levelentity.
Find Navigate
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
Navigate
ScriptDebuggerprovidesconvenientwaystoviewandnavigatethestructureofyourAppleScriptcodeinascriptwindow.
JumpByHandler
Tojumpfromhandlertohandler,successively:
ChooseEdit>GotoNextHandlerorEdit>GotoPreviousHandler.
Thehandlernameinthefirstlineofthehandlerdefinitionisselected.Handlersdonothavetobeattoplevel;forexample,ahandlerinsideascriptobjectcountsasahandler(andsodoesahandlerinsideascriptobjectinsideahandler).
NavigationBar
Thenavigationbar(abovethetextareainascriptwindow)hastwofunctions:
Itshowswhereyouare.Thecurrentselectionisdescribed,inthefollowingformat:
lineNumber:characterNumber∆lengthsymbolName
Forexample:
7:3meanstheselectionstartsatcharacter3ofline7.
∆6meanstheselectionis6characterslong(thiswillbeabsentifthere’sjustaninsertionpoint).
onmyScript'spad(s)meanstheselectionisinthehandlerpad(takingoneparameter,s),whichisitselfinsidethescriptobjectmyScript.
TheEditorpreference“Shownavigationbarlocationwhenscrolling”causesatooltip,similartothenavigationbarcontents,toappearwhenyouscrollyourscript.Thetooltipshowsthelocationofthetopofthevisibleportionofthescript.
Itletsyousurveyandnavigateyourscript’sstructure.Clickthenavigationbartosummonthetableofcontentspop-upmenu.
Themenuliststop-levelentities(scriptobjects,properties,handlers),alongwithembeddedentitiesshownhierarchically.Therearetwopossibleorders:
Alphabeticallybycategory:
Globalvariables,inalphabeticalorder.
Scriptobjects,inalphabeticalorder.
Properties,inalphabeticalorder.
Handlers,inalphabeticalorder.
Theorderinwhichtheyappearinthescript.
Theorderyou’llseedependsuponyourchoiceintheEditorpreferencescheckbox,“Sorttableofcontentsmenualphabetically.”HoldShifttodisplaythemenuintheotherorder.
HoldOptiontoeliminatepropertiesandglobalsfromthedisplay.
Youcanshowandhidethenavigationbar,tosavespace.Todoso:
ChooseView>Show/HideNavigationBar.
Thesametableofcontentsmenuthatpopsupinthenavigationbaralsoappearsinthecontextualmenu.Control-clickinthetextarea
andchooseGoTo.Thesamemodifierkeyswork(OptionandShift)ifyouholdthemwhilesummoningthecontextualmenu.
Markers
Amarkerisacommentinyourscriptthatappearsinthetableofcontentsmenusothatyoucaneasilyjumptoit.Markersalwaysappearfirstinthetableofcontentsmenu.
AmarkerisanAppleScriptcommentthatstartswith-->>.
Iftextsubstitutionisturnedon,-->>maybeconvertedto--»asyouenterit,butit’sstillamarker.
Iflinecontainsamarker,a“droplet”symbolappearsinthegutter:
GoToLine ExternalEditor
ScriptDebuggerHelp>Develop>Edit>EditingandNavigation> TableofContents
ExternalEditor
YoucanuseBBEditasanalternativetext-editingapplication.
ExternaleditingisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Thisfeatureworksseamlessly:
1. StartwithascriptwindowopeninScriptDebugger.
2. OpenthesamescriptinBBEditandedititthere.Todoso:
ChooseFile>EditWithBBEdit.app.Atemporarytextcopyofthescriptiscreated,andisopenedinBBEdit.
Theapplicationname(“XXX”)dependsonwhichapplicationsyouhaveandwhichonesarerunning.ScriptDebuggerwillpreferarunningapplicationtoonethatisnotrunning,andamongrunningapplicationsornon-runningapplicationsitwillprefertheorderBBEdit,TextWrangler,TextMate.
-->
WhileBBEditiseditingthescript,ScriptDebugger’sversionofthescriptremainsopenbutlocked.You’llseeadialogadvisingyouthatthescriptisbeingeditedelsewhere,anda“Locked”watermarkatthelowerrightofthescriptwindow.
3. InBBEdit,saveandclosethedocument.ScriptDebuggerautomaticallyadoptsthechangesyoumadeinBBEdit.
Wheneveryousavethedocumentintheexternaleditingapplication,theScriptDebuggercopyisupdatedtomatch.
Whenyouclosethedocumentintheexternaleditingapplication,thewarningdialogisremovedfromtheScriptDebuggerscriptwindow(andScriptDebuggercomestothefront).Thisisthenormalwayinwhichanexternaleditingsessionendsingoodorder.
Alternatively,youmightchangeyourmindanddecidetobreakofftheexternaleditingsessionprematurelywithoutreflectingthechangesfromBBEditbackintotheScriptDebuggerdocument.Todoso:
SwitchbacktoScriptDebuggerandclickCancelinthewarningdialog.
ThetemporarytextcopyofthescriptremainsopeninBBEdit,butitnolongerhasanyconnectiontoScriptDebugger.
Navigate
ScriptDebuggerHelp>Develop> TableofContents
Run
Whenyoucompileandrun(or“execute”)yourscript,ScriptDebuggergivesyoutoolsforunderstandingwhathappened.
Youcanviewtheresultinpowerfulways,findouthowlongyourscripttooktorun,andseethevalueofpersistentvariablesafterwards.
Ifthereareerrorswhilecompilingorrunning,theyareclearlydisplayed,withfullsupplementaryinformation.
Youcanusetheeventlogtofindoutwhatinterapplicationcommunicationstookplaceasyourscriptran.
Ifascriptableapplicationisalsorecordable,youcanrecorditwithScriptDebugger.
Youcansetascript’stargetorparentscript.
FurtherDetails:
CompileExecuteResultTimesProgressReportingVariablesErrorsEventLogRecordDefaultTargetParentScript
Edit Debug
ScriptDebuggerHelp>Develop>Run> TableofContents
Compile
Yourscriptneedstobecompiledbeforeitcanberunorsavedifithasbeenmodifiedsincethelasttimeitwasrunorsaved.
AnEditorpreference,“Showcompiledstateingutter,”causesascriptthatneedscompilingtodisplayastriped“barberpole”patterninthegutter.
Tocompileyourscript,youcan:
Compileyourcodeexplicitly.Todoso:
PressEnter(differentfrompressingReturn).
Or,chooseScript>Compile.
Or,clickCompileinthescriptwindowtoolbar.
Runthescript.Thescriptwillautomaticallybecompiledfirst.
Ascriptthatcannotbecompiledcannotberun.
Savethescript.Whenyousaveascriptthatneedscompilingtoacompiledscriptfileformat,thescriptwillautomaticallybecompiledfirst.
Ascriptthatcannotbecompiledcannotbesavedasacompiledscriptfile.
Ifyourscriptcan’tbecompiledbecauseitisn’tvalidAppleScriptcode,you’llgetanerrormessage.
Afterasuccessfulcompilation,thescriptwindowdisplaystheword“Compiled”inthestatusbar.
Toforceyourscripttorecompileevenifitdoesn’tneedcompiling,holddowntheOptionkeyandchooseScript>Recompile(orclickRecompileinthetoolbar).Thiswillalsore-initializepersistenttop-levelentitiestotheirbasevalues.Animportantsituationwhereyouwillneedtodothisiswhenyouareeditingamainscriptandareferencedlibraryscriptatthesametime.
Execute
ScriptDebuggerHelp>Develop>Run> TableofContents
Execute
ScriptDebuggercanrun(anddebug)multiplescriptssimultaneously.Toexecute(run)ascript:
ChooseScript>Execute.
Or,clicktheExecutebuttoninthetoolbar(thesecondActionbutton).
Ifthescriptneedscompiling,itisautomaticallycompiledfirst.Ifthereisacompilationerror,thescriptwon’trun.
Whileascriptisrunning:
Acircularprogressindicatorspinsattherightendofthetitlebar.
WheneveranAppleeventhasbeensenttoanapplicationbuttheapplicationhasnotyetreplied,theapplication’siconappearsattherightendofthetitlebar.IftheAppleeventisindangeroftimingout,thecircularprogressindicatorchangestoa“pie”icontrackingtheremainingtime.
Inthescriptwindowtoolbar,theExecutebuttonisdisabled,whiletheStopbutton(thefirstActionbutton)isenabled.
YoucanclickStop,orchooseScript>Stop,tointerruptexecution.
IntheScriptmenu,theExecutemenuitemchangestoRunning,isdisabled,andhasacheckmark.Script>Stopisenabled.
Additionally,ifthescriptisindebugmode,thenwhenthescriptisexecuting,thePausebuttonreplacestheExecutebuttoninthetoolbar,andScript>Pauseisenabled.
Ifthescriptrunstocompletionwithnoruntimeerror,thereisusuallyaresult.
Youcanrunthefrontmostscriptevenwhenyou’reinadifferentapplication:
UsetheMiniDebuggerfloatingwindow.Itdisplaysandletsyoucontrolthefrontmostscript.
ScriptDebugger’sDockmenu(Control-clickitsDockicon)containsExecuteandStopmenuitemsthatoperateonthefrontmostscript.
ScriptDebuggerhelpsyourunindividualhandlersinascript.
FurtherDetails:
TestingHandlers
Compile Result
ScriptDebuggerHelp>Develop>Run>Execute> TableofContents
TestingHandlers
ScriptDebuggerletsyourunindividualhandlersinascript.Thiscanbeavaluabletestinganddebuggingtechnique.
StandardEventHandlers
Youcanrunastandardeventhandler,suchasanidlehandler,anopenhandler,oraFolderActionhandler.Todoso,choosefromtheEventHandlermenu:
ChoosethehandlerfromthehierarchicalScript>Executesubmenu.
Or,holddownthemouseontheExecutebuttoninthetoolbar.Apop-upmenuappears;choosethehandlerinthismenu.
Whenyou’redebuggingascript,thesamepop-upmenuisattachedtotheTrace,StepOver,andStepOutmenuitemsandtoolbarbuttons.
Forexample,considertheappletscriptintheillustrationbelow.Ifyousimplyrunthisscript,you’llseethe“Running”dialog.That’sbecausewhatyou’vejustrunistherunhandler.Butwhatifyouwanttotesttheidlehandler?ChooseIdlefromtheEventHandlermenu.
AcontinuestatementinaneventhandlercalledinthiswaywillgenerateanerrorinScriptDebugger.Thisisdeliberateandmaybesafelyignored.Thetechnicalreasonisthatif,forexample,wepermittedacontinuequitstatementinascript’squithandlertoexecute,ScriptDebuggeritselfwouldquit.
TheCurrentEvent
WhenyouchoosefromtheEventHandlermenu,thateventbecomesthescript’scurrentevent.Thismeansthattheeventisnowcalledbydefaultwhenyourunthescript.
Toalertyoutothisspecialsituation:
Thecurrenteventischeckedinthemenu.
Ifthecurrenteventisnottherunhandler,acurrenteventindicatorappearsabovethetextareaofyourscriptwindow:
Tosetthescript’scurrenteventbacktotherunhandler:
Clickthe“x”inthecurrenteventindicator.
Or,chooseRunfromtheEventHandlermenu.
Tosetadifferentcurrenteventwithoutalsorunningthateventhandler:
HoldShiftasyouchoosefromtheEventHandlermenu.
ParametersandtheEventHistory
TheopenhandlerandtheeventhandlersdefinedintheFolderActionsandDigitalHubActionssuitesexpectparameters,whicharealiasesorfiles.
Forexample,anopenhandlerexpectsalistofaliasestothefilesandfolders.Anaddingfolderitemstohandlerexpectstwoparameters,analiastothewatchedfolderandalistofaliasestotheaddedfiles.Andsoforth.
SuchahandlerislistedintheEventHandlermenuwithanellipsis(…)afteritsname.WhenyouchooseitfromtheEventHandlermenu,ScriptDebuggerpresentsadialogwhereyoucanselectfilesandfolders.Anappropriateparameterorparameterswillthenbepassedtothespecifiedhandler.
Inthecaseofaddingfolderitemstoandremovingfolderitemsfrom,whatyou’resupplyinginthisdialogisthesecondparameter,theitem(s)thatareallegedlybeingaddedorremoved.ScriptDebuggerwillthenusethecontainingfolderoftheitem(s)asthefirstparameter,thewatchedfolder.
Inthecaseofjusttheopenhandler,thereisanotheralternative.Drag-and-dropfilesandfoldersdirectlyfromtheFinderintoyourscript.Ifyourscripthasanopenhandler,oneoftheoptionsintheresultingdialogistoinvoketheopenhandlerwiththeseFinderitemsasparameter.
ScriptDebuggerrememberseachaliasorlistofaliasesproducedinthisway,alongwiththeeventhandleritistobepassedto,andaddsthisinformationtothebottomoftheEventHandlermenu.Thislistofrememberedeventhandlersandparametersistheeventhistory.
Thus,thenexttimeyouwanttotestthissamehandlerwiththesesameparameters,youcanchooseitfromtheeventhistory(or,ifitisthecurrentevent,clicktheExecutebutton).
Theeventhistoryisremembereduntilyouclosethescriptwindow;oryoucandeliberatelyremoveitbychoosingClearMenu(whichisalwaysthelastitemintheEventHandlermenuifthereisaneventhistory).
TheeventhistoryarealsoclearedifyoumodifysettingsintheOverrideDropletBehaviorsectionofthebundlepaneofanappletorscriptbundle.
OtherHandlers
IfthehandleryouwanttotestisnotoneofthestandardeventhandlersalreadylistedintheEventHandlermenu,youcantestitusingScriptDebugger’sscriptability,whichallowsonescripttocallahandlerinanotherscript.
Forexample,supposeyouhaveopenedascriptfilecontainingthistop-levelhandler:
onjustName(s)settextitemdelimitersto":"returnlasttextitemofsendjustName--...plusalotofotherstuff...
Totestthishandlerwithoutrunningtherestofthatscript,runthisscriptfromasecondtaborscriptwindow:
telldocument2justName("this:is:a:test")endtell
ThiscallsjustNameinthefirstscript(becauseitisbehindthesecondscript,andthusisdocument2).Moreover,itaddsthishandlercallwiththisparametertotheeventhistoryofthefirstscript.Thus,havingdonethisonce,younolongerneedthesecondscriptinordertotestthefirst.
ScriptDebuggerHelp>Develop>Run> TableofContents
Result
Viewingtheresultofascriptisoftenaprimaryreasonforrunningthescript;viewingtheresultofaparticularlineofascriptisoftenaprimaryreasonfordebuggingthescript.ScriptDebuggerprovidesseveralwaystoviewaresult:
Theresultpane.Thisispartofthescriptwindow.Itisanexplorer,whichmeansyouhavethepowertoseetheresultvalueusingdifferentviews,includingBestview,whichwillbeaninteractiveoutlinerifthevalueisanobjectorcollection.
Toseetheresultpane:
ChooseView>Result&VariablesTab.
Or,clickthefirstShowbuttoninthescriptwindowtoolbar.
Theresultexplorerwindow.Thisshowstheresultinexactlythesamewayastheresultpane;thedifferenceisthatit’saseparatewindow,notpartofthescriptwindow.Thiscanbeagoodchoiceif(forexample)youwanttosavespacewithinthescriptwindow,orifyouwanttokeepviewingtheresultwhileswitchingthescriptwindow’stabstoseesomethingelse(suchastheInspectorstab).
Toseetheresultexplorerwindow,chooseScript>ShowResultExplorerWindow(orchooseShowResultExplorerWindowfromthecontextualmenuthatappearswhenyouControl-clickonthegreyareaatthetopoftheresultpane).
Theresultbar.It’sjustabar(atthetopofthetextarea),soallthere’sroomforistheresultinSourceview.Butthat’sthepoint:thisisthemostspace-savingwaytoviewtheresult.
Toseetheresultbar,chooseView>ShowResultBar.Todismisstheresultbar,chooseView>HideResultBarorclickthe“x”intheresultbar.
IntheMiniDebugger,theresultbarisalwayspresentandistheonlywaytoseetheresult(withoutswitchingbacktoScriptDebugger).
NOTE:Iftheresulthaschangedsincethepreviousexecutionofthescript,theresultpaneandresultexplorerwindowwilldisplayaredbaratthetop,andtheresultbarwilldisplaytheword“Result:”inred.Thisisparticularlyusefulindebugmode,whereanindividuallineofcodemightormightnotgenerateachangedresult.(Afteryourunascriptallthewaythroughinnormalmode,ifthere’saresult,itisalwaysnew,sotheredindicatorwillappearbydefault.)
Althoughyoucanalwaysmanuallyseetheresultinanyofthoseways,theresultissoimportantthatScriptDebuggerwouldliketoshowittoyouautomaticallyeverytimethere’saresult.AnExecutionpreference,“Showresultwhenscriptspauseorend”,determineswhichwaytheresultisdisplayedautomatically:
No.Noattemptismadetodisplaytheresultautomatically;ifitisn’tshowingalready,you’llhavetosummonitmanuallyifyouwanttoseeit.
ShowResultInspector.It’sasifyou’dchosenView>Result&VariableTab.Thiscanbeabruptifyouwerelookingatadifferenttab,butithastheadvantageofbeinganexcellentviewoftheresult,rightthereinthescriptwindow,alongwithadditionalinformationsuchasvariablevalues(and,whendebugging,thecallstack).
ShowResultBar.Theresultbarisshown,asifyou’dchosenView>ShowResultBar.
ShowResultExplorerWindow.Aseparateexplorerwindowisopened,asifyou’dchosenScript>ShowResultExplorerWindow.ThewindowappearsonlyifyoudonothavetheResult&Variabletabopen.
NOTE:Thispreferenceismeaningfulonlyiftheresultisnotalreadyshowing.Iftheresultisalreadyshowing—forexample,theresultbarortheresultpaneisvisible—thenthenewresultissimplydisplayedthere,asifthispreferenceweresettoNo.
Execute ScriptTiming
ScriptDebuggerHelp>Develop>Run> TableofContents
ScriptTiming
ScriptDebuggerautomaticallytimesyourscriptasitruns.Thisfeatureisespeciallyusefulduringdevelopmentwhenyou’retryingtomakeyourscriptasfastandefficientaspossible.
Tolearnhowlongyourscripttooktorun,justrunthescript.Thetimerinthescriptwindowtoolbardisplaysthetimings.
Thetimerdisplaysthefollowingvalues:
Thetotaltime.Thisvalueisbrokendownintotwocomponents:
TheAppleScripttime.Thisisthetimespentinternally,exclusiveoftimespentwaitingforAppleeventstoreturnfromscriptableapplicationsandscriptingadditions.
TheAppleScripttimeisaccompaniedbyapercentagefigure,showingwhatproportionofthetotaltimeitrepresents.
Theeventstime.ThisisthetimespentwaitingforAppleeventstoreturnfromscriptableapplicationsandscriptingadditions.
TheeventstimeisaccompaniedbyacountoftheAppleeventssent.
TheAppleScripttimeandtheeventstimewillsumtothetotaltime.
YoucanalsogetahandleonwhatAppleeventsarebeingsentbyusingtheeventlog.
Result ProgressReporting
ScriptDebuggerHelp>Develop>Run> TableofContents
ProgressReporting
AppleScript(startinginmacOS10.10Yosemite)hasfourpropertiesforreportingprogressthrougharepetitiveorlong-runningtask:
progressdescription,progressadditionaldescriptionTextdescribingthistask.
progresscompletedstepsThenumberofstepsofthetaskthathavebeencompletedsofar.
progresstotalstepsThenumberofstepsneededtocompletethistask.Thepercentageofthetaskthathasbeencompletedsofaristheprogresscompletedstepsdividedbytheprogresstotalsteps.Alternatively,use-1toindicateanongoingtaskofindeterminatelength(and0toindicatethatthetaskisover).
Whenprogresscompletedstepsandprogresstotalstepsarepositive,ScriptDebuggerrespondsintwoways:
Thecircularprogressindicatorchangestothe“pie”icontrackingthecompletedpercentage.
IfyouhavecheckedView>ShowProgress,theprogressbarappearsatthetopoftheeditor,displayingthe“pie”alongwiththeprogressdescription(andtheprogressadditionaldescription,ifany).
Todismisstheprogressbarprogrammatically,whileyourscriptisstillrunning,resetthepropertiesasfollows:
setprogresstotalstepsto0setprogressdescriptionto""setprogressadditionaldescriptionto""
EnhancedApplets,whicharenotavailableinLitemode,displaytheirownprogressdialog,butthecodeusedisidentical.
ScriptTiming Variables
ScriptDebuggerHelp>Develop>Run> TableofContents
Variables
Thevariablespanedisplaysthevaluesofyourscript’svariables.
Whenyousimplyrunascript,thevariablespanedisplaysthescript’spersistentvariables(top-levelentities—scriptobjects,scriptproperties,andglobals)afterexecution.Itdoesn’tshowlocalvariables,becausewhenthescriptfinishesexecuting,localvariableshavegoneoutofscope.
Whenyoudebugascript,thevariablespanealsodisplayslocalvariables.
Toseethevariablespane:
ChooseView>Result&VariablesTab.
Or,clickthefirstShowbuttoninthescriptwindowtoolbar.
Variablesaredisplayedinalphabeticalorder,groupedintothefollowingcategories:
1. Inheritedvariables(bluebackground).ThesearevariablesacquiredthroughAppleScript’sscriptobjectinheritancemechanism.
Bydefault,ascript’sparentistheAppleScriptscriptingcomponent.Therefore,thevariablespanewillusuallydisplaythisobjectanditsvariablestwice—oncebyvirtueofbeingthescript’sparent,andagainbyvirtueofbeingtheglobalscriptobjectAppleScript.
2. Requiredimportitems.Thesearetheitemsconfiguredbyusestatements,ifany.
3. Top-levelentities—scriptobjects,scriptproperties,andglobals.
Thevariablespaneisanoutliner.So:
Youcaneditthevalueofpersistenttop-levelentities(suchaspropertiesandglobals)showninthevariablespane;youmightusethisfeaturetoexperimentwithyourscript’sbehaviorunderdifferentinitialvaluesofyourpersistententities.
Inadditiontobeingabletoeditthevalueoftop-levelentities,youcanmoveitemsaroundwithinlistsbydragging,copyitemsintolists(option-drag),deleteitemsfromlistsandrecords,anddeletevariablesandscriptobjectproperties.
Recentlychangedvaluesaredisplayedinred.
ThefullversionofScriptDebuggerincludesthefollowingextrafunctionality:
Theeditingfeaturesabovealsoapplytovariableswhiledebugging.
Youcandouble-clickalineofthevariablespanetoseethatvaluedisplayedinaseparateexplorerwindow.Thevaluescanalsobeeditedintheseexplorers.
Youcanfiltertheoutlinebyshowingandworkingwiththescopebar.
Toshowthescopebar,Control-clickinthevariablespaneandchooseShowScopeBarfromthecontextualmenu.
Novariablesappearing?Showthescopebarandmakesureyou’renotfilteringthemallout.
ScriptDebuggercanpreservethevalueofpersistenttop-levelentitieswhenascriptissavedandre-opened,andbetweenscriptruns.YoucanturnthisfeatureonoroffbycheckingoruncheckingScript>PersistentProperties.
ProgressReporting Errors
ScriptDebuggerHelp>Develop>Run> TableofContents
Errors
AppleScriptgeneratestwokindsoferror—compileerrorsandruntimeerrors.ScriptDebuggerdisplaysfullinformationaboutwheretheerroroccurredandwhatwentwrong.
Ifyourscriptcatches(handles)aruntimeerrorwithatryblock,theerrordoesnotpercolateuptoAppleScriptanditisnotreportedbacktoScriptDebugger.Ineffect,thereisnoerror.Indebugmode,however,youcanbreakonanerrorevenifitiscaught.
ErrorDialog
Errorinformationisdisplayedinadialog.ThestructureofthedialogreflectsthestructureoftheerrormessagereceivedfromAppleScript.
AnerrormessagereceivedfromAppleScriptcancontainuptosixparts,correspondingtothefiveparametersoftheAppleScripterrorcommandplusanApplicationparametersuppliedbyAppleScriptitself.Thesearedisplayedinthedialogasfollows:
messagestringShownastextthetopofthedialog.
numberShownatthelowerleftofthedialog.
partialresultShownasthePartialResultpane.
fromShownastheOffendingObjectpane.
toShownastheExpectedTypepane.
[application]ShownastheApplicationpane.
Thepanesoftheerrordialogareexplorers.Ifthevaluedisplayedinapaneisanobjectreference,Bestviewisanoutliner,andindividuallinescanbedouble-clickedtocreateaseparateexplorerwindow.(SeparateexplorersarenotavailableinLitemode.)
Toshowtheerrormessagedialogagainafterdismissingit:
ChooseScript>ShowLastError.
Or,clickontheerrorlocationmarker(thearrowinthegutter).
ErrorLocation
Afteranerrordialogisdismissed,thescriptismarkedinthreeways:
Anarrowintheguttershowsthelineinwhichtheerroroccured.
Youcanclickthisarrowtodisplaytheerrormessagedialogafterdismissingthedialog.
Thelineishighlighted,andthetroublesomewordsareselected.
Theerrormessagestringisdisplayedinthestatusbar(ifyouhavenothiddentheresultbarandnootherstatusmessagehascomealongtoreplaceit).
Forinformationaboutaspecialkindoferrorsituationwhereafileisleftopen,readon.
FurtherDetails:
Leaks
Variables EventLog
ScriptDebuggerHelp>Develop>Run>Errors> TableofContents
Leaks
Ifyourscriptterminateswithaninput-outputpipeleftopen,ScriptDebuggeroffersyouthechancetocloseit.Thissituationcanarisebecause:
ThescripthascalledtheopenforaccessScriptingAdditioncommandwithoutcallingcloseaccessonthesamefile.
Whenthescriptisterminatedinthissituation,ScriptDebuggerpresentsitsLeaksdialog.Thedialogcontainsalistofopenfiles(“LeakedResources”).
Youroptionsare:
CloseAll.Allopenfilesareclosed(andtransactionsarecommitted),andthedialogisclosed.Thiswillbeyourusualchoice.
Close.Theselectedopenfileisclosed(orthetransactioniscommitted).
Abort.Theselectedtransactionisrolledback.
Forget.Theselectedleakisremovedfromthelistwithnoactiontaken.Thiswouldbeaveryunusualthingtodo,astheleakisleftopen.
Ifthescriptterminatesbecauseofanerror,theerrordialogisshowninsteadoftheLeaksdialog.Toclosealeakleftopenbytheterminationofthescript,summontheLeaksdialogmanually:
ChooseScript>ShowLeaks.
ScriptDebuggerHelp>Develop>Run> TableofContents
EventLog
Theeventlogliststhecommunicationsthatpassbetweenyourscriptandtargetapplications—Appleeventsandtheirresults.YoucanalsouseittoholdmessagessentbyyourscriptwiththeAppleScriptlogcommand.
TheeventlogpreservestheresultsofallAppleeventsperformedduringtheexecutionofascript,andletsyouexplorethoseresults.Thusitoperatesasabasicdebugger,because,veryoften,whatyousaidtoanapplicationand(especially)whatanswerthatapplicationgaveisexactlywhatyouwanttoknowaboutyourscript.
Bydefault,theeventlogisshownasapaneofthescriptwindow—theeventlogpane.Todisplaytheeventlogpane:
ChooseView>ShowEventLog.
Or,clickEventLoginthescriptwindowtoolbarsothatitishighlighted(whiteicononblackbackground).
TheAppcolumnshowstheiconoftheevent’starget,andtheTime/Dur.columnshowsthetimeelapsedsincethescriptwasstarted,plus(ingray)thedurationoftheeventinthousandthsofasecond.
Tohidetheeventlogpane:
ChoseView>HideEventLog.
Or,clickEventLoginthescriptwindowtoolbarsothatitisunhighlighted(blackicononwhitebackground).
Or,clicktheXbuttonintheeventlogpane’sscopebar(seenextsection).
Insteadoftheeventlogpane,youmayprefertoseetheloginaseparatewindow.
WARNING:Ifthelogisshowingwhileyourscriptruns,yourscriptmayrunslower(becauseoftheoverheadofdisplayingthelog’scontentsinrealtime).Ifspeed(oraccuratetiming)isoftheessence,closethelogdisplaybeforeyouexecuteyourscriptandopenitafterwards.
ScopeBar
Atthetopoftheeventlogisascopebar.Useittofilterwhatkindsofeventaredisplayedintheeventlog(describedinthenextsection).Thecontentsofthescopebarwillvary,dependingonthetargetortargetsthescriptaddresses.
Youcanshoworhidethescopebar:
Control-clickintheeventlogandchooseShow/HideScopeBarfromthecontextualmenu.
Subpanes
Theeventloghastwosubpanes:
Theeventlist.Thissubpaneisalwaysdisplayed.ItlistseachAppleevent,shownasanAppleScriptcommandandaccompaniedbyitsresult,alongwithitstimeandduration.
Eventscanbelistedinthree“languages”:
Source(AppleScript).ChooseView>LogAsSource,orclickSourceinthescopebar.
Raw(four-lettercodes).ChooseView>LogAsRaw(Chevron)Syntax,orclickRawSourceinthescopebar.
AEPrint(theactualAppleeventcontent).ChooseView>LogAsAEPrint,orclickAEPrintinthescopebar.
Eventscanalsobefiltered,usingbuttonsinthescopebar.Choicesare:
'log'Commands.Messagessentbythescriptbycallinglog.
ByApplication.AllapplicationswithwhichanAppleeventmessagewasexchangedarelisted.Ifanapplicationisn’thighlighted,itsAppleeventsarenotdisplayedinthelog.
If'log'Commandsisnothighlightedandnoapplicationishighlightedeither,theeventlogwillbeempty.
Toturnofffilteringconvenientlysothatalleventsareshown,chooseShowAllEventsfromthecontextualmenu.
Thelogresultexplorer.Thissubpaneisanexplorershowingtheresultoftheeventselectedintheeventlist.ThissubpaneisnotavailableinLitemode.Todisplaythelogresultexplorer:
ChooseView>ShowLogResultExplorer.
Or,Control-clickintheeventlistsubpaneandchooseShowLogResultExplorerfromthecontextualmenu.
AnalternatewaytoseeanexplorerforanAppleeventresult,withouttheoverheadofshowingtwosubpanesintheeventlogsimultaneously,istodouble-clicktheeventintheeventlist.Thisopensaseparateexplorerwindowontheresult.
Miscellaneous
YoucancopyanAppleeventfromthelog.Thisisthemessagesentbyyourscripttoascriptableapplication.Todoso:
Selectalineintheeventlist,andchooseFile>Copy.
Or,Control-clickandchooseCopyEventfromthecontextualmenu.
Or,drag-and-dropalineoftheeventlistintoatextenvironment.
YoucancopyaresultofanAppleeventfromthelog.Thisisthereplyreturnedbyascriptableapplicationtoyourscript.Todoso:
Control-clickandchooseCopyEventResultfromthecontextualmenu.
Ifaneventgeneratesanerror,theCopyEventResultmenuitemwillbereplacedwithCopyEventError,whichletsyoucopytheerrormessageandnumber.
Duringdebugging,acorrespondenceismaintainedbetweeneachAppleeventandthelineofthescriptwhereitwasperformed.Tohighlightthecorrespondingscriptline:
Selectalineintheeventlist.
Bydefault,eventsremainintheloguntilthenextexecutionofthescript—thatis,thedefaultpolicyistoclearthelogwhenexecutionbegins.Youcanmodifythispolicy.Toclearthelogimmediately:
ChooseScript>ClearEventLog.
Or,clicktheClearbuttonintheeventlog’sscopebar.
Justtheopposite,topreventthelogfrombeingclearedwhenthenextexecutionbegins:
ChooseScript>AppendToEventLog(sothatitischecked).
FurtherDetails:
EventLogWindow
Errors Record
ScriptDebuggerHelp>Develop>Run>EventLog> TableofContents
EventLogWindow
Ascriptcandisplayitseventloginaseparatewindow,insteadoftheeventlogpaneinthescriptwindow.
Todisplaytheeventlogwindow:
ChooseScript>ShowEventLoginWindow.
Ascript’seventlogwindowhasthesefeatures:
Itscontentisthesameastheeventlogpane.
Itistiedtothescript:
Ifthescriptissaved,thesizeandconfigurationofitseventlogwindowissaved.
Ifthescriptisclosed,itseventlogwindowisclosed.
Thescriptcanbesavedwhentheeventlogwindowisfrontmost.Theeventlogwindow’s“dirty”status(theClosebutton)isthesameasthescript’s“dirty”status.
Theeventlogwindow’sstatusbarmatchesthescript’sstatusbar.
Theexecutionofthescript(includingdebugmodesteppingandtracing)canbecontrolledfromtheeventlogwindow.CommandssuchasScript>CompileandScript>Executeworkwhenaneventlogwindowisfrontmost,andbuttonsforthemappearinthetoolbar,asdoesthetimer.
Inthisway,youcanworkintheeventlogwindowandconcentrateyourattentiononit,whilerunningordebuggingthescript.
ScriptDebuggerHelp>Develop>Run> TableofContents
Record
Ifascriptableapplicationisalsorecordable,ittranslatesuseractionsintoAppleScriptcode.ThisiseffectivelythesameAppleScriptcodethatwouldbeusedtoperformthosesameactionsprogrammatically.Commonexamples(perhapstheonlyexamples)ofrecordableapplicationsareBBEditandtheFinder.
Tostartrecordinguseractions:
ChooseScript>Recordandswitchtotherecordableapplication.(YoucanalsoaddaRecordbuttontothescriptwindowtoolbar;inthatcase,youcanclicktheRecordbuttontostartrecording.)
Or,ifyou’realreadyintherecordableapplication,chooseRecordfromScriptDebugger’sDockmenu.
Onceyou’vestartedrecordinguseractions,performactionsdirectlyintherecordableapplication.ScriptDebuggerwillrecordtheAppleScriptequivalentofeachaction.Whenyou’redonerecording:
SwitchtoScriptDebuggerandchooseScript>Stop(orclicktheRecordbuttoninthetoolbaragain).
Or,chooseStopfromScriptDebugger’sDockmenu.
ScriptDebuggerletsyoumanipulateobjectsinitsDictionaryExplorerview–forexample,youcanmove,copyanddeletefilesintheFinder.Ifyouturnonrecording,theseExploreractionswillalsoberecorded.Youcanseehowthisformofrecordingworksinthisdemonstrationvideo
EventLog DefaultTarget
ScriptDebuggerHelp>Develop>Run> TableofContents
DefaultTarget
ScriptDebuggerletsyousetanapplicationasyourscript’simplicittarget.ThisistheapplicationtowhichundirectedAppleeventsshouldbesent.
Tosetanimplicittarget:
ChooseScript>DefaultTargetandselectthedesiredtargetapplication.Allapplicationsinthedictionarieslistappearaschoices.
Thenameofthedefaulttargetappearsasatelllineatthetopofthescript,remindingyouthatthescriptisnowwrappedinavirtualtellblockdirectedatthisapplication.
Toremovetheimplicittarget:
ChooseScript>DefaultTarget>None.
Or,clickthe“x”inthetellbaratthetopofthescript.
Thisfeatureisusefulforsimulatingruntimeenvironmentswherethereisanimplicittarget.Forinstance,ifyourscriptistorunfromBBEdit’sScriptsmenu,codethattargetsBBEditdoesn’thavetoappearinatellblock,becauseyou’re“inside”BBEditalready.TotestorrunsuchascriptfromwithinScriptDebugger,youneedawaytomakeBBEditthedefaulttarget,andthat’swhatthisfeatureprovides.
Record ParentScript
ScriptDebuggerHelp>Develop>Run> TableofContents
ParentScript
ScriptDebuggerletsyousetanotherscriptastheimplicitparentofthecurrentscript.ThemechanisminvolvedisAppleScript’sscriptobjectinheritance.
SupportforparentscriptsisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Tosetaparent–childrelationshipbetweentwoscripts:
Bothscriptsmustbeopen.
Bringthe“child”scriptfrontmost.ChooseScript>ParentScriptandthenameoftheparentscript.
Thisparent-childrelationshippersistsonlywhilebothscriptsareopen.Ifyoutrytoclosetheparentscript,you’llgetadialogwarningthatyou’reabouttobreaktheparent-childrelationship.
Thisfeaturecanbeemployedtomakeasetoftop-levelentities(properties,handlers,etc.)fromonescriptavailableinanother(forexample,youcoulduseittestindividualhandlersinascriptwithoutalteringthatscript),orforsimulatingaruntimeenvironmentwhereparentscriptrelationshipsareused.
Note:Neitherthe“parent”scriptnorthe“child”scriptmaybeindebugmode.
DefaultTarget
ScriptDebuggerHelp>Develop> TableofContents
Debug
MeetScriptDebugger’sdebugmode.Debuggingascriptislikerunningit,exceptthatindebugmodeyourscriptcanpauseinthemiddle.
Debuggingisaseparatemode;it’safeatureofyourscript.Ascriptiseitherindebugmodeoritisn’t.
DebuggingisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Toturnondebugmodeforascript:
ChooseScript>EnableDebugging.Ifthemenuitemischecked,debugmodeison.
Or,clicktheDebuggingbuttoninthescriptwindowtoolbarsothatitishighlighted(whiteicononablackbackground).
Whenyourscriptisindebugmode:
1. Inthetoolbar,theStepbuttons(Trace,StepOver,StepInto,StepOut)areaddedtotheActioncontrol,andtheBreakpointsbuttonappears(bydefault).
2. TheDebuggingbuttoninthetoolbarhasawhiteicononablackbackground.
3. Thegutteriswider(inordertoaccomodatebreakpointsandcodecoveragemarkers),anddisplayspausearrowsnexttoeverylineofthescriptwhereit’spossibletosetabreakpoint.
4. IntheResult&Variablestab,twoadditionalpanesappear:thecallstackandthebreakpointsinspector.
Toturnoffdebugmode:
ChooseScript>EnableDebugging.Ifthemenuitemisunchecked,debugmodeisoff.
Or,clicktheDebuggingbuttoninthescriptwindowtoolbarsothatitisunhighlighted(blackicononwhitebackground).
NOTE:Youmighthavetostopyourscript(chooseScript>Stop,orclickStopinthetoolbar)beforeyoucanturnoffdebugmode.Youcan’tturnoffdebugmodeifyourscriptisrunningorpaused.
Debugmodeisascriptfeature;itissavedaspartofascriptfile.ItisalsouniquetoScriptDebugger.AscriptsavedindebugmodeisunusableexceptinScriptDebugger.Therefore,whenyou’refinisheddebugging,youwillprobablywanttosaveyourscriptnotindebugmode.
Thereis,however,onegoodreasonfordeliberatelysavingascriptindebugmodeandrunningitelsewhere—sothatyoucandebugexternally.
Debugmodegivesyourscript(andyou)manynewpowers.
Yourscriptcanpauseinthemiddleofexecution.
Amajorconcernduringdebuggingwillbe:wherewillyourscriptpause?Theanswerinvolveschieflytheinterplaybetweenbreakpointsandthesteppingcommands.
Whilepaused,youcansee(andalter)thevaluesofyourscript’svariables,alongwithotherAppleScriptvalues,astheychangeduringthecourseofexecution.
Youcanseewhatcodeisexecutedandwhatchoicesyourcodemakes.Youcanalsorunyourcodeinslowmotion,watchingitspathofexecution.
Youcanobservehowonehandlercallsanother.
Ifyourscriptinvolvesdrivingascriptableapplication’sinterface,itmayhelpyoutoworkintheMiniDebugger,whereyoucaninteractwithbreakpointsandpausesinyourscriptwhilekeepingthescriptableapplicationfrontmost.
FurtherDetails:
PauseExecuteWhenDebuggingBreakpointsStepTraceCallStackVariables(DebugMode)ExpressionsExceptionsCodeCoverageExternalDebuggingTheMiniDebugger
Run
ScriptDebuggerHelp>Develop>Debug> TableofContents
Pause
Thekeyfeatureofdebugmodeisthatyourscriptcanpauseinthemiddleofexecution.Clickheretolearnhowtopauseyourscript.
DebuggingmodeandpausingarefeaturesofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Whenascriptispausedindebugmode:
TheExecutecommandbecomestheResumecommand.Thus,Script>ExecutebecomesScript>Resume,andtheExecutebuttoninthetoolbarresumesexecution.
Script>Pauseisdisabledandchecked.
The“paused”iconappearsattherightendofthetitlebar(and,ifthisscriptisinatab,attherightsideofthetab).
Thestatusbarreports“Paused”andpossiblythepauselocation.
Agreenarrowinthegutterindicatesthelineatwhichyourscriptispaused.
NOTE:Thelinepointedtobythegreenarrowhasnotyetbeenexecuted.
WhyPause
Thepointofpausing(andofdebugging)isthatwhileyourscriptispaused,youcanexamineitsstate.
Forexample,youcanstudythecallstack,thevaluesofyourvariables,thevaluesofexpressions,andtheeventlog.
Thenyoucanmakeyourscriptproceedagain(andpossiblypauseagain).
Pausingvs.Stopping
Distinguishpausingfromstopping!
Pausingispossibleonlyindebugmode.Itleavesyousomewhereinthemiddleofexecution.Fromhere,youcanproceedfurther,evencompletingthescriptnormallyifyouwantto.
Whenpaused,youcannotturnoffdebugmode.Youmuststopthescriptinordertoturnoffdebugmode.
Whenpaused,youcannotedityourscript.Youmuststopthescriptinordertoeditit.
Stoppingascript,ontheotherhand,ispossibleatanytime.Stoppingabortsexecutionimmediatelyandreturnseverythingtoneutralstate.Ifyouexecutethescriptfromhere,you’llbestartingattheverybeginning.
Tostopascript:
ChooseScript>Stop.
Or,clickStopinthetoolbar.
FurtherDetails:
HowtoPause
ExecuteWhenDebugging
ScriptDebuggerHelp>Develop>Debug>Pause> TableofContents
HowtoPause
Themostimportantthingtounderstandaboutdebuggingiswhenyourscriptwillpause.
PausingisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Executionwillpauseautomaticallyifthepathofexecutioncomestoanenabledbreakpoint.Executionpauseswiththegreenarrowpointingatthebreakpointedline,andbeforeexecutingthebreakpointedline.
YoucansuspendthisrulebychoosingScript>BreakonBreakpointssothatitisunchecked.Otherwise,enabledbreakpointstakepriorityovereverythingelse.
Thestepcommandscauseexecutiontoproceedbyalimitedamountandthenpause.
Eachstepcommandhasitsownruleforwhat“alimitedamount”means(discussedhere).
Butremember,unlessyou’vesuspendedbreakpoints,breakpointstakepriority.Ifastepcommandisinprocessandthepathofexecutionhitsanenabledbreakpoint,thestepcommandiscancelledandexecutionpausesatthebreakpoint.
Ifyou’veelectedtobreakonexceptions,encounteringaruntimeerrorwillpauseyourscript—evenifyourscriptcatchesandhandlestheerror.
Duringalengthyboutofexecution(ortracing),youcanmanuallypausethescript:
ChooseScript>Pause.
Or,clickPauseinthetoolbar.
Ifyourscriptispausedbutyoucan’tseewhere(becauseyou’vescrolledtoexaminesomeotherregionofthescript),chooseEdit>GotoCurrentLinetobringthelinecontainingthegreenarrowintoview.
Whatisthepathofexecution?
Asyourscriptruns,onelineisexecuted,thenanother,thenanother.Therearebranches,sosomelinesmightbeskipped.Thereareloopsandhandlers,sosomelinesmightbeexecutedseveraltimes.Thus,linebyline,likeamouserunninginamaze,thecomputertracesapathofexecutionthroughyourcode.(Youcanactuallywatchthishappeningindebugmode,bytracing.)
ScriptDebuggerHelp>Develop>Debug> TableofContents
ExecuteWhenDebugging
Thesefeaturesrelyondebuggingnode,whichisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Hereisasummaryofthewaysyoucanstartorresumeexecutionindebugmode.
ChooseScript>ExecuteorScript>Resume(theyarethesamemenuitem).
Or,clicktheExecute/Resumebuttoninthetoolbar(theyarethesamebutton).
ChooseScript>Trace.
Or,clickTraceinthetoolbar.
IssueanyStepcommand.
IssuetheExecute(orTrace)toHerecommand.Thiseffectivelysetsabreakpointandstartsorresumesexecutionatthesametime.
Theabilitytotestindividualhandlers(andtheeventhistory)appliesindebugmodeexactlyasinnormalmode,onlyevenmoreso.NotonlyExecutebutalsoTraceandtheStepcommandshavetheEventHandlermenu.(ButnotStepOut,becauseitcan’tbeusedtoinitiateexecutionfromastoppedstate;whenthescriptisstopped,you’renot“in”anythingthatyoucanstep“out”of.)
Pause Breakpoints
ScriptDebuggerHelp>Develop>Debug> TableofContents
Breakpoints
Indebugmode,executionofyourscriptwillpauseifthepathofexecutionencountersanenabledbreakpoint.Whenascriptpausesatabreakpoint,itpausesbeforeexecutingthebreakpointedline.
BreakpointsareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Youcancreateabreakpointonlyindebugmode,butthebreakpointisnotlostifyouleavedebugmode—itwillstillbetherethenexttimeyouswitchtodebugmode.Breakpointsaresavedwhenyousaveacompiledscriptindebugmode.Theyarelostwhenyousaveacompiledscriptinnormalmodeandclosethescript.
Placeswhereyoucansetabreakpointareshownas“executable”arrowsinthegutterofthescriptwindow.
SettingandRemovingBreakpoints
Tosetabreakpoint:
Clickan“executable”arrow(orthegutternexttoit).
Or,selectwithinthedesiredline;thenchooseScript>SetBreakpoint.
Or,Control-clickinthedesiredline(orinthe“executable”arrow),andchooseSetBreakpointfromthecontextualmenu.
Abreakpointmarkerappearsinthegutter.
Tomoveabreakpoint:
Dragthebreakpointupordowntheguttertoadifferent“executable”arrow.
Toremoveabreakpoint:
Selectwithinthebreakpointedline;thenchooseScript>RemoveBreakpoint.
Or,Control-clickinthebreakpointedline(orinthebreakpoint),andchooseRemoveBreakpointfromthecontextualmenu.
Or,Control-clickthebreakpoint’slistinginthebreakpointsinspectorandchooseDeletefromthecontextualmenu.
Or,dragthebreakpointrightoutofthegutter.
Toremoveallbreakpoints:
ChooseScript>RemoveAllBreakpoints(holdCommandtoseeit).
Or,Control-clickinthescript(orinthegutter)andchooseRemoveAllBreakpointsfromthecontextualmenu.
EnablingandDisablingIndividualBreakpoints
Anindividualbreakpointcanbeenabledordisabled.Adisabledbreakpointdoesn’tactlikeabreakpoint,butit’snotremoved,either,soyoucanenableitlaterifyoulike.Adisabledbreakpoint’smarkeristransparent;anenabledbreakpoint’smarkerissolid.
Todisableabreakpoint:
Clickthebreakpointmarker.
Or,selectwithinthebreakpointedline;thenchooseScript>DisableBreakpoint.
Or,Control-clickinthebreakpointedline(orinthebreakpoint),andchooseDisableBreakpointfromthecontextualmenu.
Or,uncheckthebreakpoint’slistinginthebreakpointsinspector.
Toenableabreakpoint:
Clickthebreakpointmarker.
Or,selectwithinthebreakpointedline;thenchooseScript>EnableBreakpoint.
Or,Control-clickinthebreakpointedline(orinthebreakpoint),andchooseEnableBreakpointfromthecontextualmenu.
Or,checkthebreakpoint’slistinginthebreakpointsinspector.
TIP:Youcanalsoenableordisableabreakpointwithacheckboxinitsconditionsandactionspopover.Double-clickthebreakpointtoseethepopover.
Withsomebreakpointsdisabled,youcanremovejustthosebreakpointsthatareenabled.Todoso:
ChooseScript>RemoveAllDisabledBreakpoints(holdShiftandCommandtoseeit).
Or,Control-clickinthescript(orinthegutter)andchooseRemoveAllDisabledBreakpointsfromthecontextualmenu.
EnablingandDisablingtheEntireBreakpointMechanism
Youcanalsodisabletheentirebreakpointmechanism.Ifthebreakpointmechanismisdisabled,breakpointmarkersareshowningrey.Ifthebreakpointmechanismisenabled,breakpointmarkersareshownincolor.
Todisabletheentirebreakpointmechanism:
ChooseScript>BreakonBreakpointssothatitisunchecked.
Or,clickBreakpointsinthetoolbarsothatitisunhighlighted(blackicononwhitebackground).
Toenabletheentirebreakpointmechanism:
ChooseScript>BreakonBreakpointssothatitischecked.
Or,clickBreakpointsinthetoolbarsothatitishighlighted(whiteicononblackbackground).
Or,enableanydisabledbreakpoint.Thebreakpointmechanismisautomaticallyenabledasawholewhenyouenableanindividualbreakpoint.
FurtherDetails:
TemporaryBreakpointsExecutetoHereBreakpointsInspectorConditionsandActions
ExecuteWhenDebugging Step
ScriptDebuggerHelp>Develop>Debug>Breakpoints> TableofContents
TemporaryBreakpoints
Atemporarybreakpointisabreakpointwhichautomaticallyremovesitselfwhenencounteredbythepathofexecution.
Thus,wewillpausethere,butonlyonce;afterthat,thebreakpointwillbegone.Thisisconvenient,forexample,topausethefirsttimethroughacertainloopbutnotonsubsequentiterations,orthefirsttimeacertainhandleriscalled.
TemporarybreakpointsareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Tosetatemporarybreakpoint:
Option-clickan“executable”arrow(orthegutternexttoit).
Or,selectwithinthedesiredline;thenchooseScript>SetTemporaryBreakpoint(holdOptiontoseeit).
Or,Control-clickinthedesiredline(oninthe“executable”arrow),andchooseSetTemporaryBreakpoint.
TIP:Youcanalsotogglethetemporarystatusofabreakpointwithacheckboxinitsconditionsandactionspopover.Double-clickthebreakpointtoseethepopover.
Anenabledtemporarybreakpointmarkerisshowninyellow.
Disablingatemporarybreakpointalsoturnsitintoanormalbreakpoint.Thereisnosuchthingasadisabledtemporarybreakpoint.
Option-clickinganexistingnormalbreakpointturnsitintoatemporarybreakpoint.Option-clickinganexistingtemporarybreakpointturnsitintoanormalbreakpointandalsodisablesit.
ExecutetoHere
ScriptDebuggerHelp>Develop>Debug>Breakpoints> TableofContents
ExecutetoHere
Youmightwantexecutiontoproceedtoacertainlineandpausethere,withouttheoverheadofsettingabreakpoint.That’swhat“Executetohere”does.It’sashortcutforsettingatemporarybreakpointfollowedbyexecuting.
ExecutetohereafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Touse“executetohere”:
Shift-clickan“executable”arrow(orthegutternexttoit,oranexistingbreakpointmarker).
Or,selectwithinthelineyouwanttoexecuteto,andchooseScript>ExecuteToHere.
Or,Control-clickthelineyouwanttoexecuteto(orinthe“executable”arrow),andchooseExecuteToHerefromthecontextualmenu.
Ifabreakpointisencounteredbeforethetargetlineisreached,wewillpauseatthatbreakpoint,andthetemporarybreakpointcreatedby“ExecutetoHere”willremaininplace.
Avariantof“executetohere”is“tracetohere”,whichisthesameexceptthatwetraceinsteadofexecutingatnormalspeed.Touse“tracetohere”:
Option-Shift-clickan“executable”arrow(orthegutternexttoit,oranexistingbreakpointmarker).
Or,selectwithinthelineyouwanttoexecuteto,andchooseScript>TraceToHere.
Or,Control-clickthelineyouwanttoexecuteto(orinthe“executable”arrow),andchooseTraceToHerefromthecontextualmenu.
TemporaryBreakpoints BreakpointsInspector
ScriptDebuggerHelp>Develop>Debug>Breakpoints> TableofContents
BreakpointsInspector
Thebreakpointsinspectorliststhebreakpointsinyourscripts.Here,youcanmanageyourbreakpoints,plusyoucanviewandeditabreakpoint’sconditionsandactions.
ThebreakpointsinspectorisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Thebreakpointsinspectorappearsinascriptwindowindebugmodeinthesametabastheresultpaneandthevariablespane.Toseethebreakpointsinspector:
ChooseView>Result&VariablesTab.
Or,clickthefirstShowbuttoninthescriptwindowtoolbar.
Thebreakpointsinspectorfunctionsasalistofbreakpoints,throughwhichyoucanmanageascript’sbreakpoints.Youcan:
Seethelocationofeachbreakpoint.ThelinenumberisgivenintheLine#column,andyoucanselecttheline:
Double-clickthebreakpointlisting.
Or,Control-clickabreakpointlistingandchooseGoToSourceLinefromthecontextualmenu.
Seehowmanytimesabreakpointhasbeenencounteredduringthisexecutionofthisscript.ThenumberisgivenintheHitscolumn.
Enableordisableabreakpoint:
Checkorunchecktheboxinthefirstcolumn.
Changethenameofabreakpoint:
Clickthename,orselectalineandpressReturn,tomakethenameeditable.
Thedefaultnameofabreakpointisthetextofthebreakpointedline.
Deleteabreakpoint:
SelectabreakpointlistingandchooseEdit>Delete.
Or,control-clickabreakpointlistingandchooseDeletefromthecontextualmenu.
Sortthelist:
Clickacolumnheader.
Readontolearnaboutbreakpointconditionsandactions.
ExecutetoHere ConditionsandActions
ScriptDebuggerHelp>Develop>Debug>Breakpoints> TableofContents
ConditionsandActions
Breakpointconditionsandactionscangiveabreakpointtremendousadditionalpower:
Aconditionmeansthatwhenthepathofexecutionhitsthebreakpointedline,wemightormightnotpausehere.
Anactionisanextrabehaviorperformedbythebreakpointwhenthepathofexecutionpausesatthebreakpointedline.
BreakpointconditionsandactionsareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Toseeandeditconditionsandactionsattachedtoabreakpoint:
Inthescriptgutter,double-clickthebreakpoint;or,selectinthelineandchooseScript>EditBreakpoint.Theconditionsandactionsappearinapopoverbesidethebreakpoint.
Inthebreakpointsinspector,selectthebreakpointlistingandpressRightArrow(orclickthetriangleinthebreakpointlisting).
Conditions
Therearetwokindsofcondition.Ifoneconditionischecked,wewillpauseatthisbreakpointonlyifthecheckedconditionistrue.Ifbothconditionsarechecked,wewillpauseatthisbreakpointonlyifbothconditionsaretrue.
Hitcount.Wepausewithrespecttohowmanytimesthisbreakpointhasbeenencounteredduringthisexecution.Youcansetanumberoftimesandacomparisonoperator.
(Recallthattheactualhitcountisvisibleinthelastcolumnofthebreakpointsinspector.)
Expression.EnteranAppleScriptexpressioninthetextfield.Theexpressionisevaluatedwhenthebreakpointisencountered.Wewillpauseornot,basedon:
Theexpression’struthvalue.Theexpressionmustevaluatetoaboolean;itisnotimplicitlycoercedtoaboolean.
Or,theexpression’sexceptionvalue.Youcanpausebecausetheexpressiondoesordoesnotgenerateanexception(aruntimeerror).
Actions
Therearethreekindsofaction;youcanspecifyasmanyasyoulike.Actionsareperformedonlyifwewouldpauseatthisbreakpoint(becausethebreakpointisencounteredbythepathofexecutionanditsconditions,ifany,aretrue).
Postamessagetotheeventlogand/orthestatusbar.
Thestatusbarmessageappearsinbracketsafterthenormalstatusbarcontent.Asubsequentstatusbarmessagecan,ofcourse,replacethisone.
Clearthehitcount.
Ifthisbreakpointisencounteredagainduringthisexecution,thehitcountwillberecordedas1.
Performanexecutioncommand.Whatshouldhappenwhenwehitthisbreakpoint?Thedefaultcommand(thethingthatusuallyhappensatabreakpoint)isPause,butyoucanchooseanyotherexecutioncommand,includingStop,Resume(i.e.
proceedwithoutpausing),oranyofthestepcommands.
BreakpointsInspector
ScriptDebuggerHelp>Develop>Debug> TableofContents
Step
TherearethreeStepcommands—StepOver,StepInto,andStepOut.
SteppingisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
ToissueaStepcommand:
ChooseitfromtheScriptmenu.
Or,clickthebuttoninthetoolbar.(TheStepcommandsarethethird,fourth,andfifthActionbuttons.)
Intheaboveillustration,thethreebuttonsareStepOver,StepInto,andStepOut,inthatorder.
ThethreeStepcommandsdifferwithrespecttowhereexecutionwillpauseafterwards.We’llusethecodeintheillustrationbelowtoshowwhatthedifferentStepcommandsmean.Intheillustration,weareinitiallypausedatabreakpointatline9(withoutyethavingexecutedline9).
StepIntoisthesimplest.Itmeans,“Executethecurrentlineofcode,andthen,whereverthepathofexecutiontakesyou,pauserightthere,onthenextlinethatwouldbeexecuted.”
So,intheillustrationabove,StepIntowouldcausethescripttopauseatline5.Why?Becauseline9,wherewearepaused,callsthepadhandler.Sowhenweexecuteit,we’lldiveintothepadhandler,andthenextexecutablelinewherewecanpause,inthatpathofexecution,isline5.
StepOverissimilartoStepInto,exceptthatitfollowsanadditionalrule,“Don’tpauseinadeeperlevelofthecallstackthanwhereyouarerightnow.”
So,intheillustrationabove,StepOverwouldcausethescripttopauseatline10.Why?Becausethat’sthenextexecutablelinethatisn’tatadeeperlevel.Line9,wherewearepaused,callsthepadhandler,whichisadeeperlevel,sowedon’tpauseuntilthenextexecutablelineafterthepathofexecutionhasreturnedfromthepadhandler.
StepOutmeans,“Executeuntilyoucometothenextexecutablelineatahigherlevelofthecallstackthanwhereyouarerightnow,andthenpause.”
So,intheillustrationabove,StepOutwouldcausethescripttopauseatline13.Why?Wearepausedatline9,ins’simplicitrunhandler.Weexecutetotheendoftherunhandler,whichisline10,andreturnfroms’simplicitrunhandler.Nowweareatahighlevel,sowewanttopause.Infact,weareinline12,becausethatiswheres’srunhandlerwascalled.Butwedon’tpauseinline12,becauseifweweregoingtopausethere,itwouldbebeforeexecutingline12andbeforetellingstorun.Sonowwe’reatline13.
Allofthosedetailsarepredicatedonthesuppositionthatnobreakpointsareencountered.Suppose,forexample,that
therewereanenabledbreakpointatline5(andassumethatScript>BreakonBreakpointsischecked,andthatthisbreakpointhasnoconditions).Thepathofexecutionpassesthroughline5,soallthreecommandswoulddoexactlythesamething—pauseatline5.Breakpointstakepriority.
BothStepOverandStepIntocanbeusednotonlytoresumebutalsotostartexecutionofascript.Inthiscasetheybothpausebeforethefirstexecutablelineofthescript.
BothStepOverandStepIntohavethesameoptionsforexecutinghandlersastheExecutebutton.
Breakpoints Trace
ScriptDebuggerHelp>Develop>Debug> TableofContents
Trace
Tracingislikeexecuting,onlyit’sslower—slowenoughthatyoucanactuallyseethegreenarrowmovingalongthepathofexecution.
TracingisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Totrace:
ChooseScript>Trace.
Or,clickTraceinthetoolbar.(ItisthesixthActionbutton.)
Thespeedoftracingisdeterminedbythetracespeedslider.Toseethetracespeedslider:
ChooseScript>Trace.Thesliderisinthehierarchicalmenu(theEventHandlermenu).
Or,havingcustomizedthetoolbarsothatitincludesthetracespeedslider,usethesliderinthetoolbar.
Thetracespeedsliderrangesbetween“tortoise”attheleftand“hare”attheright.
Tracingisinonesensejustaslowerformofexecution,andwillpauseforthesamereasons(e.g.,becauseabreakpointisencountered,orbecauseyouissuethePausecommand).However,what’sreallyhappeningisthatScriptDebuggerispausingandresumingaftereveryexecutedline.Thismeansthatyoucanseemorethanthegreenarrowmoving—youcanalsoseethecallstackgrowingandshrinking,andthevariablevalueschanging,andsuccessiveresultsappearing,justasyouwouldifyouifwererepeatedlyissuingtheStepIntocommand.
TracehasthesameoptionsforexecutinghandlersasExecute.
Step CallStack
ScriptDebuggerHelp>Develop>Debug> TableofContents
CallStack
Whenascriptispausedwhiledebugging,youcanviewthenestofhandlercallscurrentlybeingexecuted.Thisisthecallstack(orcallchain).
ThecallstackisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Whatisthecallstack?
Executiontypicallystartswiththescript’srunhandler(implicitorexplicit).Codeinthishandlercancallanotherhandler,whichcancallanotherhandler(orthesamehandler,recursively),andsoon.Thus,atanygivenmomentduringtheexecutionofyourcode,thereisanestorchainofhandlersleadingdownfromtopleveltothelinecurrentlybeingexecuted.
Thecallstackisdisplayedinascriptwindowindebugmodeinthesametabastheresultpaneandthevariablespane.Toseethecallstack:
ChooseView>Result&VariablesTab.
Or,clickthefirstShowbuttoninthescriptwindowtoolbar.
Eachentryinthecallstackisastackframe.Thestackframesareorderedfrominnermost(themostrecenthandlercall)tooutermost(theoldesthandlercall,usuallythescript’srunhandler).Thus,intheaboveillustration,top-levelcodeispausedinthepadhandlerofthescriptobjects.
Stackframesnewlyaddedsincethelasttimethescriptpausedareshowninred.
Whenmultiplestackframesexist,thescriptcan,inasense,bepausedatmorethanonelinesimultaneously.(Thus,intheaboveillustration,wearepausedatthreeplaces,whoselinenumbersaregiveninthelastcolumn.)Therefore,thescriptisdisplayedwithmultiplegreenarrows.Thelinewherewearereallypaused(withinthedeepeststackframe)hasasolidgreenarrow;theothershavetransparentgreenarrows.
Astackframe,andtheplacewherethescriptispausedwithinit,representanentireenvironment.Onestackframeisalwaystheselectedstackframe;bydefault,itisthedeepeststackframe.Theenvironmentreflectedinthescriptwindowchangeswhenadifferentstackframeisselected.Whenyouselectastackframe:
Thelineofthescriptwherewe’repausedinthatstackframeishighlighted.
Thevariablespanechangestoreflectthevariablevaluesinscopeinthatstackframe.
Expressionsarere-evaluatedagainstthatstackframe.
Trace Variables(DebugMode)
ScriptDebuggerHelp>Develop>Debug> TableofContents
Variables(DebugMode)
Whenascriptispausedwhiledebugging,thevariablespanedisplaysallvariablescurrentlyinscopeintheselectedstackframe.
DebuggingisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Important:Thisincludeslocalvariables—butlocalvariablesmustbeexplicitlydeclaredlocal(withalocalstatement),ortheywon’tbeshown.
Variablesaredisplayedinalphabeticalorder,groupedintothefollowingcategories:
1. Inheritedvariables(bluebackground).
Ascript’spersistentvariablesincludethoseacquiredthroughAppleScript’sscriptobjectinheritancemechanism.
Bydefault,ascript’sparentistheAppleScriptscriptingcomponent.Therefore,thevariablespanewillusuallydisplaythisobjectanditsvariablestwice—oncebyvirtueofbeingthescript’sparent,andagainbyvirtueofbeingtheglobalscriptobjectAppleScript.
2. Localparameters(greenbackground).Theseareincomingparametervalues,andareshownifthecurrentlyselectedstackframeisahandlerwithparameters.
3. Localvariables(yellowbackground).Thesearelocaltothecurrentlyselectedstackframe.Youprobablywon’tseetheseunlessyouexplicitlydeclareyourlocals.
4. Top-levelentities.
Thevariablespaneisanoutliner,withallthatthisentails.
Theabilitytoeditavariablevalueisespeciallyusefulwhenpausedwhiledebugging,becauseyoucanexperimentallyalterthebehaviorofyourscriptasitproceedstothenextline.
Anotherwaytoseevariablevaluesisthroughtooltipsthatappearwhenyouhoverthemouseoveranexpressioninyourscript.AnExecutionpreference,“Showexpressiontooltips,”setstheconditionsunderwhichtheseappear.
CallStack Expressions
ScriptDebuggerHelp>Develop>Debug> TableofContents
Expressions
AnexpressionisasnippetofAppleScriptcodethathasavalue.Expressionsareevaluatedeverytimethescriptpauses.Thisincludesthepointwherethescriptcompletes.Expressionsarelikelytobemostusefultoyouwhenpausedduringdebugging.However,youcancreateandeditexpressionsatanytime.Expressionsareafeatureofascript,andaresavedwhenyousaveacompiledscript.
ExpressionsareafeatureofthefullversionofScriptDebugger;theyarenotavailableinLitemode.
Important:Anexpressionmayrefertolocalvariables—butlocalvariablesmustbeexplicitlydeclaredlocal(withalocalstatement),ortheexpressionwon’tbeableto“see”them,andwillreportthatthevariableisundefined.
Expressionsarecreated,edited,anddisplayedintheexpressionspane,whichisinthesametabastheresultpaneandthevariablespane.Toseetheexpressionspane:
ChooseView>Result&VariablesTab.
Or,clickthefirstShowbuttoninthescriptwindowtoolbar.
Tocreateanexpression:
Clickthe+buttonintheexpressionspane.
Or,chooseScript>NewExpression.
Or,selectwithinascriptandchooseScript>CopyToExpressions.
Toeditanexpression:
SelectitandpressReturn.
Toforcere-evaluationofanexpression:
SelectitandpresstheRefreshbutton.
Or,selectitandchooseDictionary>Reload(orchooseDictionary>ReloadAll).
Or,Control-clickitandchooseReload(orReloadAll)fromthecontextualmenu.
Toremoveanexpression:
Selectitandclickthe-buttonintheexpressionspane.
Or,Control-clickitandchooseDeletefromthecontextualmenu.
Or,chooseScript>ClearAllExpressions(removesallexpressions).
Theexpressionspaneissimilartothevariablespane:
Anexpressionwhosevaluehaschangedsincethelastpauseisshowninred.
Anexpressionisre-evaluatedwhenyouselectadifferentstackframeinthecallstack.Theexpressionmightrefertoalocalvariable,andlocalvariablenamescanhavedifferentmeaningsindifferentstackframes.
Theexpressionspaneisanoutliner,withallthatthisentails.
Note:Evaluatinganexpressionislikerunningalittleone-linescript,andevenalittleone-linescriptcandopowerfulthings.Anexpressionthatchangesavariable’svalue,orcallsahandlerinyourscript,canbeavalidexpressionandthereforecanhaveside-effectseachtimeitisevaluated.
Variables(DebugMode) Exceptions
ScriptDebuggerHelp>Develop>Debug> TableofContents
Exceptions
Ahandledruntimeerror(anexception)cancauseapausewhendebugging,likeabreakpoint.
Ahandledruntimeerrorisanerrorthatoccurswithinatryblock.Itwouldnotnormallycauseanybreakintheaction,becauseAppleScriptwillcontinueexecutionintheonerrorclause,or(ifthereisnoonerrorclause)afterthetryblock.ButScriptDebuggercanoptionallypausewhenitdetectsahandledruntimeexception.
PausingonexceptionsisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Anunhandledruntimeerrorcausesexecutiontoabortentirely,sothereisnoquestionaboutpausingthere—thescriptwilldomorethanpause,itwillstop.
Topauseathandledruntimeerrors:
ChooseScript>BreakonExceptionssothatitischecked.
Optionally,youcanaddanExceptionsbuttontothescriptwindow’stoolbarthattogglesbreakingonexceptions(andreflectsthestateofthattoggle).
IfBreakonExceptionsischeckedandahandledruntimeerrorisencounteredwhiledebugging,executionpausesmuchasifthiswereabreakpoint,justbeforetheexceptionisactuallythrown.Variablesandexpressionsareevaluatedatthatpoint.Aredarrowmarksthelinewheretheerroroccurs.
Tolearnwhattheerrorwas,whilepausedattheerror:
Lookatthestatusbar;itcontainstheerrormessage,asisusualforerrors.
ChooseScript>ShowLastError;or,clicktheredarrow.Thissummonsthenormalerrordialog.
Optionally,youcanaddaShowLastErrorbuttontothescriptwindow’stoolbar.
EvenifBreakonExceptionsisunchecked,andahandledruntimeerrordoesnotcauseapause,youcanstilllearn,atthefirstpauseaftertheerrorisencountered,wheretheerrorwas(theredarrowisstillpresent)andwhattheerrorwas:
ChooseScript>ShowLastError;orclicktheredarrow.
Onceyouresumeexecutionofthescript,theexceptionmarkisremoved(andShowLastErrorwillnolongerrecoverit).
Expressions CodeCoverage
ScriptDebuggerHelp>Develop>Debug> TableofContents
CodeCoverage
Codecoveragemarksshowthelinesofyourscriptthatwereactuallyexecutedindebugmode.Thiscanhelpyousurveythepathofexecutionwithouttracingorstepping.Forinstance,youcaneasilyseewhetherthereareareasofthescriptthatareneverbeingexecuted.
CodecoverageisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
Whencodecoverageison,circlesappearintheguttermarkingexecutablelinesthathavebeenencounteredbythepathofexecution.Thesizeofthecirclesisrelative:smallercircleshavebeenencounteredfewertimes.Thecolorofthecircleswillalsochange,fromgraythroughyellowtored.Theactualnumberofhits(thenumberoftimesexecutionhaspassedthroughaline)isshowninatooltipwhenyouhoverthemouseoveracircle.
Toturnoncodecoverage:
ChooseScript>ShowCodeCoveragesothatitischecked.
Toclearcodecoveragecircleswithoutturningcodecoverageoff:
ChooseScript>ClearCodeCoverage.
Codecoveragecirclesareresetautomaticallywhenyouexecutethescriptfromthestart.
Exceptions ExternalDebugging
ScriptDebuggerHelp>Develop>Debug> TableofContents
ExternalDebugging
YoucaninitiateascriptoutsideScriptDebuggerandstilldebugitinScriptDebugger.ThescriptopensinScriptDebuggerandyoucanpauseatbreakpoints,resumeorstepthroughthescript,andsoforth.Thisiscalledexternaldebugging.
ExternaldebuggingafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
ExternaldebuggingisprobablytheonlysituationwhereitmakessensetosaveascriptindebugmodeandyetpermitittoruninsomeapplicationotherthanScriptDebugger.
Itisofteneasiertouseexternaldebuggingandtestascriptundertheconditionsinwhichitwillactuallyrunthantotrytosimulatethoseconditionsartificially.Agoodcandidateforexternaldebuggingisanapplet,afolderaction,anAppleMailrulescript,aBBEditmenuitemscript,oranyscriptthatistobetriggeredautomaticallybysomeotherapplication.Externaldebuggingisespeciallyusefulwhenparametersaresuppliedaspartofthecallthattriggersthescript,sinceitshowsyouwhatthoseparametersare.
Itoftenhappensthatthehostapplicationtriggersthescriptbycallingintoahandler.Inthatcase,thishandlerbecomesthecurrentevent.Thecurrenteventindicatorappearsatthetopofthescript,andthecallisrecordedintheeventhistory.Youcanthensubsequentlycallthesamehandleragainwiththesameparameters,directlyfromwithinScriptDebugger.
Toperformexternaldebugging:
1. Saveacompiledscriptindebugmode.
2. Triggerthescriptinsomeotherapplication.
ThescriptopensautomaticallyinScriptDebuggerifitwasn’topenalready.
IfthescriptwasalreadyopeninScriptDebuggerwhenitistriggered,itremainsopenafteritfinished.Ifitwasn’talreadyopeninScriptDebugger,thenwhenthescriptfinishes,itcloses.
Ifthescriptwasn’talreadyopeninScriptDebuggerbeforehand,thenameofthescript,inthescriptwindow’stitlebar,willappearasthenameofthehostapplicationwith“(Debugging)”appendedtoit,asasignthatexternaldebuggingisproceedinginatemporarywindow.
SwitchingtheFrontmostApplication
VariousExecutionpreferencesdeterminehowScriptDebuggerwillbehavewithregardtopausing,andwithregardtobringingitselfandtheinitiatingapplicationtotheforeground:
“Pausescriptwhenexternaldebuggingbegins.”Ifchecked,ScriptDebuggerinsertsatemporarybreakpointbeforethefirstexecutableline,andpausestherewhenthehostapplicationinitiatesthescript.Thisgivesyouachancetoconfigurebreakpoints,forexample.
“Restoreactiveapplicationwhenstepping/continuing.”Ifchecked,thehostapplicationisbroughtbacktothefrontwhenresumingafterapause.
“BringScriptDebuggertoforegroundwhenscriptspause.”Ifchecked,ScriptDebuggerisbroughttothefrontwhenthescriptpauses.
“BringScriptDebuggertoforegroundwhenscriptsends.”Ifchecked,ScriptDebuggerisbroughttothefrontwhenthescriptends.
IfyoudecidethatScriptDebuggershouldnotbringitselftotheforeground,youcanstillcontroldebuggingfromwithinthehostapplicationbyusingtheMiniDebugger.
Hands-OnExample
Here’sanexample,usinganAppleMailrulescript.Arulescriptisstructuredlikethis:
usingtermsfromapplication"Mail"onperformmailactionwithmessagestheMessagesforruletheRuletellapplication"Mail"--dousefulthingshereendtellendperformmailactionwithmessagesendusingtermsfrom
Compilethatscript,putitindebugmode,placeabreakpointonthe“tell”line,saveit,andthen(inMail)nominatethisscriptastheRunAppleScriptactioninaRule.TriggertherulebyselectingsomemessagesandchoosingMessage>ApplyRules.Dependingonthechoicesyoumadeinthepreferences,ScriptDebuggermaynowcometothefront;inanycase,itispausedatthebreakpointedline.YoucanexaminetheMessagestoseewhatmessagesMailhasmatchedupwithyourrule’scriteria.Moreover,performmailactionisthecurrentevent,andhasbeenadded,withtheseparameters,totheeventhistory.
CodeCoverage TheMiniDebugger
ScriptDebuggerHelp>Develop>Debug> TableofContents
TheMiniDebugger
TheMiniDebuggerisafloatingwindowthatputsScriptDebugger’sfrontmostscriptwindowinfrontofallapplicationsonyourscreen.
TheMiniDebuggerisafeatureofthefullversionofScriptDebugger;itisnotavailableinLitemode.
MostAppleScriptcodeinvolvestargetingscriptableapplications(andsomeAppleScriptcodeiscalledbyotherapplications,aswithexternaldebugging).ThusitisoftenconvenienttohavesomecontroloverScriptDebuggerwhilekeepingsomeotherapplicationfrontmost,sothatyoucanworkinorobservethatapplication,withoutchangingthelayeringorderamongyourapplications.That’swhattheMiniDebuggerletsyoudo.
TosummontheMiniDebugger:
ChooseWindow>MiniDebugger.
Ifyou’reinanotherapplication,chooseMiniDebuggerfromScriptDebugger’sDockmenu.
TheMiniDebuggerwindowcontains:
Areducedversionofthescriptwindowtoolbar,showingonlytheActionbuttons.ThereisalsoaScriptDebuggertoolbarbutton;clickittobringScriptDebuggerfrontmost.
Thegutter.Youcansetbreakpointsandseecodecoverage.
Theresultbar.Thisgivesthelatestresultateachpause,insourceview.
Aminimallyeditabletextarea.Youcaneditthescriptusingkeystrokes,andthetextareacontextualmenuworks.Fulleditingfeaturessuchascodecompletion,however,areabsent.
ExternalDebugging
ScriptDebuggerHelp> TableofContents
Reference
Thisisthereferencesection.
ItsurveysScriptDebugger’smenus.
ItdescribesScriptDebugger’spreferences.
ItdiscussesScriptDebugger’swindows.
Itprovidesabriefglossaryandanswerssomefrequentlyaskedquestions.
FurtherDetails:
MenusPreferencesWindowsGlossaryFrequentlyAskedQuestions
Develop
ScriptDebuggerHelp>Reference> TableofContents
Menus
ThisisareferencesectiondescribingallofScriptDebugger’smenus.
Youcancustomizethekeyboardshortcutforamenuitem:
OpenScriptDebugger’sPreferenceswindowandgototheKeyBindingspane.
Hint:Insomecaseswhereyoufindyourselfusingacommandoften,youmayfindthatatoolbaritemissupplied.ChooseView>CustomizeToolbarandexaminetheavailabletoolbaritems.Ifthecommandhasatoolbaritem,youcandragitintothetoolbar,andfromthenonyoucanusethattoolbaritemasawayofissuingthecommand.
FurtherDetails:
ApplicationMenuFileMenuEditMenuViewMenuSearchMenuScriptMenuDictionaryMenuWindowMenuClippingsMenuScriptsMenu
Preferences
ScriptDebuggerHelp>Reference>Menus> TableofContents
ApplicationMenu
AboutScriptDebugger7
Displayscopyrightinformation,acknowledgements,andlicensingdetails.
SendUsEmail
Inyourpreferredemailprogram,createsanewemailmessageaddressedtoLateNightSoftware.
CheckForUpdates
GoesonlinetocheckwhetherthereisamorerecentreleaseofScriptDebugger.ASoftwareUpdatepreferenceallowsyoutosetthisactiontobeperformedautomaticallyatfixedintervals.
PurchaseScriptDebugger
TakesyouinyourbrowsertotheLateNightSoftwarewebsite,whereyoucanbuyaScriptDebuggerlicense.
Enter/ChangeLicense
Presentsadialogwhereyoucanenterorre-enterregistrationinformation.
Preferences
SummonsthePreferenceswindow.
OthermenuitemsinthismenuarestandardmacOSapplicationmenucommands.
FileMenu
ScriptDebuggerHelp>Reference>Menus> TableofContents
FileMenu
NewScript
Createsanewscriptwindow,sizedandconfiguredaccordingtoyoursaveddefaults,ifany.
IftheGeneralpreference“ForNewDocuments”is“ShowTemplateChooser”,thetemplatechooserappearsinstead.
NewScriptFromTemplate
Showsthetemplatechooserforcreationofanewscriptwindow.
NewScriptTab
Createsanewscriptasatabinthefrontmostscriptwindow.
IftheGeneralpreference“ForNewDocuments”is“ShowTemplateChooser”,thetemplatechooserappearsinstead.
NewScriptTabFromTemplate
Showsthetemplatechooserforcreationofanewscripttab.
Open
Bringsupafiledialogwhereyoucanchooseascriptfile(toopenitforediting)oranapplication(toopenitsdictionary).
OpenQuickly
BringsupadialogwhereyoucanenterpartofthenameorcontentsofascripttodoaSpotlightsearch.
OpenRecent
Lists,andletsyouopen,recentlyopenedscripts.
OpenDictionary
PresentsahierarchicalmenuwhereyoucanopenthedictionaryofascriptingadditionoranapplicationintheRunning,Recent,orFavoritescategoryofthedictionarieslist.Toopenthedictionaryofanapplicationnotlistedhere,chooseApplication(thefirstiteminthismenu).
OpenXXXDictionary
Opensthedictionaryforthecurrenttellcontext.
OpenScriptLibrary“XXX”
Opensalibraryscriptfile(oritsdictionary)whentheselectionisinalinereferringtothelibraryscript.(Alternateswiththepreviousmenuitem.)
OpenExplorerWindow
Opensthecurrentlyselectedoutlineriteminaseparateexplorerwindow.(Alternateswiththepreviousmenuitem.)
CloseTab
Closesthefrontmostwindow;ifthefrontmostwindowisascriptwindowconsistingofmultipletabs,closesthecurrenttab.Ifclosinga“dirty”script,you’llbeofferedachancetosaveit.
CloseWindow
Closesthefrontmostscriptwindow,evenifitconsistsofmultipletabs.Ifanyofthescriptsinthosetabsare“dirty”,you’llbeofferedachancetosavethem.
CloseAll
Closesallwindows.Ifanyscriptsare“dirty”,you’llbeofferedachancetosavethem.
Save
Savesthefrontmostscript.Ifthefrontmostscripthasneverbeensaved,workslikeSaveAs.
SaveAs
Bringsupadialogforsavingthefrontmostscriptasanewfile,possiblyinadifferentformat.
SaveACopyAs
SimilartoSaveAs,exceptthatafterwardsthescriptwindowshowstheoldfile,notthenewlycreatedfile.
SaveAll
PerformsaSaveonevery“dirty”script.
RevertTo
Showsasubmenu.Ifthedocumenthasbeensavedbuthasunsavedchanges,therewillbeaRevertToSavedmenuitem,showingthetimeanddateofthelastsaved.Ifthedocumenthasbeensavedmorethanonce,therewillbeaBrowseAllVersionsmenuitem,allowingyoutobrowsepreviousversions.
RecoverDamagedScript
Bringsupadialogwhereyoucanchooseascriptfiletoopenastextifpossible.Thetextispastedintoanewuntitledscriptwindowortab.
ExportRun-OnlyScript
Savesacopyofthecurrentscriptasarun-onlyscript.
SaveasTemplate
Savesacopyofthecurrentscriptasausertemplate,toappearinthetemplatechooserasabasisforfuturenewscripts.
EditWithBBEdit
OpensatextcopyofthecurrentscriptinBBEdit,initiatinganexternaleditingsession.
ShowManifest
Bringsupadialoglistingthecurrentscript’sdependencies.
ScriptFormat
Letsyousettheformatinwhichthescriptshouldbesaved.Onlyformatscompatiblewiththescript’spresentformatareenabled;tochangetoanotherformat,chooseFile>SaveAs.
ApplicationOptions
Ifthescriptisanapplet(eitherAppleorEnhanced),letsyousetitsappletoptions.
CodeSigning
Ifthescriptisanappletorcompiledscriptbundle,letsyoucodesignit(orturnoffcodesigning).
RevealinFinder
RevealsintheFinderthecurrentdocument(forasavedscript),application(foradictionary),orreference(foraselectedreferencetoaFinderiteminanoutliner).
OpeninNewWindow
Opensanadditionalwindowonthecurrentscriptordictionary.
QuickLook
Displays,usingQuickLook,thecurrentlyselectedreferencetoaFinderitem(aliasorfilereference)inanoutliner.
PageSetup
StandardmacOSpagesetupcommand.Bringsupthestandarddialogforpreparingtoprint.
StandardmacOSprintcommand.Bringsupthestandarddialogforprintingthefrontmostscriptordictionary.
Youcanforceapagebreakintheprintedoutputofascriptbyincludingtheword!pagebreak!inacommentatthepointwhereyouwantanewpagetostart.
ApplicationMenu EditMenu
ScriptDebuggerHelp>Reference>Menus> TableofContents
EditMenu
Undo
Undoesthemostrecentchangetothecurrentscript.
Redo
Undoesthemostrecentundotothecurrentscript.
Cut
Movesselectedtextfromthecurrentscripttotheclipboard.Thisincludesformattedtextsuitableforpastingintoawordprocessor.
Copy
Copiestheselectedmaterialtotheclipboard.Theselectionmightbe(forexample)textinascriptoraresult,textintheinfopaneofadictionarywindow,atermintheterminologylistofadictionarywindow,alineoftheeventlog,oralineofanoutliner(inwhichcasewhatiscopiedisanAppleScriptreference).Thisincludesformattedtextsuitableforpastingintoawordprocessor.
CopyValue
Copiesthevalue(insteadofareference)oftheselectedlineofanoutliner.(Alternateswiththepreviousmenuitem;holdShifttoseeit.)
Paste
Pastestheclipboardintothecurrentselectioninascript.
PasteAsStringLiteral
Pastestheclipboardintothecurrentselectioninascript,wrappedinquotationmarks(unlesstheinsertionpointisalreadyinsideastringliteral).Internalquotationmarks,tabs,andline-endcharactersareescaped.
PasteTell
Presentsahierarchicalmenushowingthedictionarieslist,fromwhichyoucanchooseanapplication.Pastesatellblockintothecurrentselectioninascript.Ifnoscriptwindowisopen,orifyouholddowntheOptionkey,createsanewscriptwindowcontainingthetellblock.
Forarunningapplication,furtherhierarchicalmenusallowyoutopasteareferencetoanobjectintheapplication’sobjectmodel.
Delete
Clearstheselectedtextwithoutmovingittotheclipboard.Alsoworksonanyselectableremovableentity(anexpression,abundleresource,etc.).
SelectAll
Selectsalltextinthecurrentselectioncontext.
Complete
Invokescodecompletion,likepressingescorF5.
Balance
Selectssurroundingdelimitersorblockboundaries.
CodeFolding>Fold/Unfold
Collapsesorexpandstheblockcontainingtheselection.
CodeFolding>UnfoldAll
Expandsallcollapsedblocksinthescript.
CodeFolding>Fold/UnfoldHandlers
Collapsesorexpandsallhandlersinthescript.
CodeFolding>Fold/UnfoldBlockComments
Collapsesorexpandsallblockcommentsinthescript.
AppleScriptObjC>…
ClickheretoreadaboutAppleScriptObjCrefactoring.
GotoLine
Presentsadialogallowingyoutojumptoalineofascriptbyitslinenumber.
GotoCurrentLine
Scrollstothelineofascriptthathasthegreenarrowindebugmode.
GotoPrevious/NextHandler
Selectsandscrollstothestartofthenextorprevioushandlerinthescript.
GotoPrevious/NextPlaceholder
Selectsandscrollstothenextorpreviousplaceholderinthescript.
CommitPlaceholder
Turnsthecurrentlyselectedplaceholderinthescriptintonormaltext.
SplitEditorVertically/Horizontally
Splitsthescriptwindoweditingarea.
CloseSplitView
Closesthecurrentsplitpaneinthescriptwindoweditingarea.
CloseAllScriptViews.
Closesallsplitpanesinthescriptwindoweditingarea.(Alternateswiththepreviousmenuitem;holdOptiontoseeit.)
ShiftLeft/Right
Removesoraddsalevelofindentationtothelinescontainingtheselection.
Comment/Uncomment
Addsorremovesalevelofcommentcharacterstothestartofthelinescontainingtheselection.
Entab/Detab
Changesleadingindentationtotabsorspacesinthelinescontainingtheselection.
StartDictation
StandardmacOSdictationcommand.
Emoji&Symbols
StandardmacOScharacterchoosercommand.
FileMenu ViewMenu
ScriptDebuggerHelp>Reference>Menus> TableofContents
ViewMenu
Show/HideToolbar
Togglesvisibilityofthetoolbarforthecurrentwindow.
CustomizeToolbar
Bringsupthedialogforcustomizingthecontentsofthetoolbarforthecurrentwindowtype.
Show/HideTabBar
Togglesdisplayofthescriptwindowtabbar.Ifthetabbarisshowing,itwillbepresentevenifthewindowcontainsonlyasinglescript.
Show/HideNavigationBar
Togglesvisibilityofthenavigationbarinthescriptwindow.
Show/HideResultBar
Togglesvisibilityoftheresultbarinthescriptwindow.
Show/HideStatusBar
Togglesvisibilityofthestatusbarinthescriptwindow.
ShowProgress
Ifchecked,theprogressbarwillappearinresponsetoprogressreportingcommands.
Result&VariablesTab
Inthescriptwindow,togglesvisibilityoftheresultpane,thevariablespane,theexpressionspane,andthecallstackpaneandbreakpointspane(whendebugging).
ResourcesTab
Inthescriptwindow,togglesvisibilityofthescript’sdescriptionandthebundleinspector(ifthescriptisinabundleformat).
InspectorsTab
Inthescriptwindow,togglesvisibilityoftheclippingsinspector,thedictionariesinspector,andthetellcontextinspector.
BestViewSourceViewAEPrintView
Switchesbetweenviewsinthecurrentexplorerpaneorexplorerwindow.HoldShifttoshowmultipleviewssimultaneously.
Show/HideEventLog
Togglesdisplayoftheeventlogpaneinthescriptwindow.
Show/HideEventLogResultExplorer
Togglesdisplayofthesecondpaneoftheeventlogpaneoreventlogwindow,consistingofanexplorerontheresultoftheAppleeventselectedintheeventlist.
LogAsSource/Raw(Chevron)Syntax/AEPrint
Changesthe“language”usedtodisplayeventsintheeventlistoftheeventlogpaneoreventlogwindow.
ShowCodeFolding
Togglesvisiblityofcodefoldingsymbols,andenablingofcodefoldingcommands,inthecurrentscript.
ShowLineNumbers
Togglesvisibilityoflinenumbersinthecurrentscript.
ShowTabStops
Togglesvisibilityoftabstopsinthecurrentscriptorexplorer.
ShowInvisibles
Togglesvisibilityofinvisiblecharactersinthecurrentscriptorexplorer.
ShowSpaces
Togglesvisibilityofspacecharactersinthecurrentscriptorexplorer.
WrapLines
Toggleslinewrappinginthecurrentscriptorexplorer.
PrettyPrint
Togglespretty-printinginthecurrentexplorer.
ShowRaw(Chevron)Syntax
TogglesdisplayofterminologyasrawAppleeventcodesinthecurrentscript,explorer,ordictionary.
Enter/ExitFullScreen
StandardmacOSfull-screenmodecommands.
EditMenu SearchMenu
ScriptDebuggerHelp>Reference>Menus> TableofContents
SearchMenu
Find
Inascriptwindow,orinadictionarywindowdisplayingtheinfopane,summonsthefindbar.
Find&Replace
Inascriptwindow,summonsthefindbarinReplacemode.
FindAgain
Findsthesearchstring,searchingforwards,startingatthecurrentselection.
FindAgainBackwards
Findsthesearchstring,searchingbackwards,startingatthecurrentselection.
FindSelection
CopiesthecurrentselectionasthesearchstringandperformsaFindAgain.
FindSelectionBackwards
CopiesthecurrentselectionasthesearchstringandperformsaFindAgainBackwards.
UseSelectionforFind
Copiesthecurrentselectionasthesearchstring.
UseSelectionforReplace
Copiesthecurrentselectionasthereplacestring.
Replace
Replacesthecurrentselectionwiththereplacestring.
Replace&FindAgain
PerformsaReplacefollowedbyaFindAgain.
Replace&FindAgainBackwards
PerformsaReplacefollowedbyaFindAgainBackwards.
ReplaceAll
Replacesallinstancesofthesearchstringwiththereplacestring.BehaviorisaffectedbytheWrapcheckbox.
LookUpDefinition
Inascript,copiesthecurrentselectionintothesearchfieldofthedictionariesinspectorandperformsthesearch.Inadictionarywindow,putsthefocusinthesearchfieldinthetoolbar.
ViewMenu ScriptMenu
ScriptDebuggerHelp>Reference>Menus> TableofContents
ScriptMenu
TheScriptmenuappliestothecurrentscriptwindowortab.Ifnoscriptwindowisfrontmost,theScriptwindowmenuitemsaredisabled.
Compile
Compilesthescript.
Recompile
ForcesrecompilationevenwhenAppleScriptdoesn’tthinkthescriptneedscompiling.(Alternateswiththepreviousmenuitem;holdOptiontoseeit.)
Record
TurnsonAppleScriptrecordingmode,sothatuseractionsinrecordableapplicationsarewrittenintothescript.Itcanalsobeusedtorecordactionsintheapplicationexplorer.
Execute
Runsthescript,compilingitfirstifnecessary.Whenpausedindebugmode,becomesResume,andcontinuesexecutionfromthepausedline.Submenusallowstandardhandlerstobecalledindividually.
Trace
Indebugmode,startstracing.Submenusdisplaythetracingspeedsliderandallowstandardhandlerstobecalledindividually.
Stop
Abortstherunningscript.
Pause
Indebugmode,pausesthescriptafterthelinecurrentlybeingexecuted.
StepOver,StepInto,StepOut
Thestepcommands,usedindebugmode.Submenusallowstandardhandlerstobecalledindividually.
EnableDebugging
Togglesonoroffdebugmode.
PersistentProperties
Togglesonoroffpersistenceofglobalvariableswhenascriptisclosedandlateropened.
ShowResultExplorerWindow
Showstheresultasaseparateexplorerwindow.
ShowLastError
Showstheerrordialogforthemostrecentlyencounterederror.
ShowLeaks
Showstheleaksdialog.
ShowCodeCoverage
Togglescodecoveragedisplayonoroff.
ClearCodeCoverage
Removescodecoveragemarkswithouttogglingcodecoverageoff.
ShowEventLoginWindow
Showstheeventlogwindowforthecurrentscript.
ClearEventLog
Removesalleventsfromtheeventlog.
AppendToEventLog
Ifchecked,theeventlogisnotautomaticallyclearedwhenbeginninganewexecutionofthescript.
BreakonExceptions
Indebugmode,toggleswhetherornothandledruntimeerrorscauseapause.
BreakonBreakpoints
Indebugmode,toggleswhetherornotbreakpointsareenabledgloballyforthisscript.
EditBreakpoint
Summonstheconditionsandactionspopoverforthecurrentlyselectedline’sbreakpoint.
Set/Disable/EnableBreakpoint
Createsortogglestheenabledstatusofabreakpointatthecurrentlyselectedline.
SetTemporaryBreakpoint
Createsatemporarybreakpointatthecurrentlyselectedline.(Alternateswiththepreviousmenuitem;holdOptiontoseeit.)
RemoveBreakpoint
Removesthebreakpointatthecurrentlyselectedline.
RemoveAllBreakpoints
Removesallbreakpoints.(Alternateswiththepreviousmenuitem;holdCommandtoseeit.)
RemoveAllDisabledBreakpoints
Removesalldisabledbreakpoints.(Alternateswiththepreviousmenuitem;holdShiftandCommandtoseeit.)
ExecutetoHere
Setsatemporarybreakpointatthecurrentlyselectedlineandstartsorresumesexecution.
TracetoHere
Setsatemporarybreakpointatthecurrentlyselectedlineandstartstracing.(Alternateswiththepreviousmenuitem;holdCommandtoseeit.)
NewExpression
Createsanewemptyexpression,readyforediting.
CopyToExpressions
Createsanewexpressionbycopyingthecurrentselection.
ClearAllExpressions
Deleteseveryexpression.
DefaultTarget
Setstheimplicittargetforthescript.
ParentScript
Setstheparentofthescripttoanothercurrentlyopenscript.
SearchMenu DictionaryMenu
ScriptDebuggerHelp>Reference>Menus> TableofContents
DictionaryMenu
TheDictionarymenuappliestothecurrentdictionarywindow.Ifnodictionarywindowisfrontmost,theDictionarywindowmenuitemsaredisabled.
Reload
Inexplorerview,reloadsinformationthat’shierarchicallydependentonthecurrentlyselectedline.
ReloadAll
Inexplorerview,reloadsallinformation.(Alternateswiththepreviousmenuitem;holdOptiontoseeit.)
PasteTell
Insertsatellblockintothecurrentscript.
Launch/ActivateXXX
StartsuporbringstothefronttheapplicationXXX.
QuitXXX
QuitstheapplicationXXX.
ShowDictionariesList
Togglesvisibilityofthedictionarieslistinthedictionarywindow.
ShowDictionary
Inthedictionarywindow,displaystheterminologylistandtheinfopane.
ShowObjectModel
Inthedictionarywindow,displaystheobjectmodeldiagramandtheinfopane.
ShowContainment
Inthedictionarywindowobjectmodeldiagram,displaysthecontainmenthierarchy.
ShowInheritance
Inthedictionarywindowobjectmodeldiagram,displaystheinheritancehierarchy.
ShowExplorer
Inthedictionarywindow,displaystheapplicationexplorer.
GoBack/Forward
Navigatesthehistoryinthedictionaryinfopaneorexplorer.
ShowInheritedDefinitions
Toggleswhetherornottheinheritedpropertiesandelementsappearinthisdictionary’sdisplay.
ShowExtraDocumentation
Toggleswhetherornotextendedexplanatorycontentappearsinthisdictionary’sdisplay.
LargerText/SmallerText
Increasesordecreasesthesizeofinformationinthisdictionary’sdisplay.
ScriptMenu WindowMenu
ScriptDebuggerHelp>Reference>Menus> TableofContents
WindowMenu
Minimize
StandardmacOSwindowminimizationcommand.
Zoom
StandardmacOSwindowzoomcommand.
BringAlltoFront
StandardmacOScommandforbringingalltheapplication’swindowsforward,outfrombetweenthoseofotherapplications.
SelectNextTab/SelectPreviousTab
Navigatebetweentabsinthecurrentscriptwindow.
MergeAllWindows
Mergesallopenscriptwindowsandtabsastabsinthefrontmostwindow.
BringAlltoFront
StandardmacOScommandforbringingalltheapplication’swindowsforward,outfrombetweenthoseofotherapplications.
SetDefaultScript/DictionaryWindow/ExplorerWindowSize&State
Savestheconfigurationofthecurrentscriptwindow,dictionarywindow,orexplorerwindowasamodelforfuturenewones.
ResetDefaultScript/DictionaryWindow/ExplorerWindowSize&State
Revertstothedefaultconfigurationforfuturenewscriptwindows,dictionarywindows,orexplorerwindows.
Dictionary
Switchestothefrontmostdictionarywindow,oropensanewdictionarywindow.
NewDictionaryWindow
Opensanewdictionarywindow.Bydefault,thesameasthepreviousmenuitem,plusShift.
MiniDebugger
OpensthefloatingMiniDebuggerwindow.
TheWindowmenualsolistsallopenwindows.Tabsareshownhierarchicallydependentontheirwindowtitle.
DictionaryMenu ClippingsMenu
ScriptDebuggerHelp>Reference>Menus> TableofContents
ClippingsMenu
TheClippingsmenu( )accessesclippings.Eachmenuitemrepresentsafile(orfolder)storedinoneoftwoplaces.
ThefirstplacefilesarefoundiswithintheScriptDebuggerbundle.Theyappearasmorethan30menuitems,withasubmenucontainingmanymoreAppleScriptObjCclippings(thelatterdonotappearinLitemode).
Youcanaddyourownmenuitems(andsubmenus)bystoringclippingsfilesandfoldersin~/Library/ApplicationSupport/ScriptDebugger7/Clippings.YoucanopenthisfolderbychoosingScripts>OpenClippingsFolder.Anyitemsinthisfolderwillappearatthetopofthemenu,withtheapplication-supplieditemsbelow,separatedbyadivider.
Afilewillappearasamenuitem.Afolderwillappearasahierarchicalmenu,andthefilesinsideitwillbeitsmenuitems.Thenameofafile(orfolder)isthenamethatwillappearinthemenu,exceptthatcertainnamesorpart-namesarehiddenandusedfordeterminingtheorderofthemenu,asfollows:
Ifanamestartswiththeprefix#),where#isawholenumberofanylength,thatnumberdeterminesthepositionofthisiteminthemenuandtheprefixdoesnotappearinthemenuitem’sname.
Aname#)-***willappearasamenuseparator,againwithitsorderdeterminedbythewholenumber#.
HerearetheactionsyoucanperformwiththemenuitemsintheClippingsmenu:
Chooseamenuitemtoinsertthatclippingintothecurrentscriptwindow.
HolddowntheOptionkeywhilechoosingamenuitemtoopenthatclippingforediting.ThisonlyappliestoscriptsinyourClippingsfolder.
HolddowntheShiftkeywhilechoosingamenuitemtorevealtheclippingfileintheFinder.ThisonlyappliestoscriptsinyourClippingsfolder.
WindowMenu ScriptsMenu
ScriptDebuggerHelp>Reference>Menus> TableofContents
ScriptsMenu
TheScriptsmenu( )accessesauxiliaryscripts.Eachmenuitemrepresentsafile(orfolder)storedinoneoftwoplaces.
ThefirstplacefilesarefoundiswithintheScriptDebuggerbundle.Theyappearasfivemenuitems:
OpenScriptsFolder
OpenClippingsFolder
OpenTemplatesFolder
OpenScriptLibrariesFolder
ImportClippings
Thefirstfouritemsareself-explanatory.ImportClippingscanbeusedtocopyoneormoreclippingsfilesfromScriptDebugger’sbundletoyourClippingsfoldersotheyappearinyourClippingsmenu,soyoucancustomizethem.
Scriptscanalsolivein~/Library/ApplicationSupport/ScriptDebugger7/Scripts/.Thisiswhereyoucanstoreyourownscripts.
IfthereareanyitemsintheLibraryScriptsfolder,theywillappearatthetopoftheScriptsmenu,separatedfromtheapplication-providedscriptsbyadivider.Afilewillappearasamenuitem.Afolderwillappearasahierarchicalmenu,andthefilesinsideitwillbeitsmenuitems.
Thenameofafile(orfolder)isthenamethatwillappearinthemenu,exceptthatcertainnamesorpart-namesarehiddenandusedfordeterminingtheorderoftheusersectionofthemenu,asfollows:
Ifanamestartswiththeprefix#),where#isawholenumberofanylength,thatnumberdeterminesthepositionofthisiteminthemenuandtheprefixdoesnotappearinthemenuitem’sname.
Aname#)-***willappearasamenuseparator,againwithitsorderdeterminedbythewholenumber#.
HerearetheactionsyoucanperformwiththemenuitemsintheScriptsmenu:
Chooseamenuitemtorunthatscript.
HolddowntheOptionkeywhilechoosingamenuitemtoopenthatscriptfileforediting.ThisonlyappliestoscriptsinyourLibraryfolder.
HolddowntheShiftkeywhilechoosingamenuitemtorevealthescriptfileintheFinder.ThisonlyappliestoscriptsinyourLibraryfolder.
ScriptsintendedfortheScriptmenumaybeAppleScriptscripts,shellscripts,Automatorworkflows,orAppleScriptapplications.Ashellscriptmusthaveanidentifyingfilenameextension(thiswillusuallybe.sh).
Thescriptsarerunbyaseparateprocess,similartothewayscriptsarerunfromApple'sScriptsmenu.
ClippingsMenu
ScriptDebuggerHelp>Reference> TableofContents
Preferences
WhenyouchoosethePreferencesmenuitemfromtheapplication(ScriptDebugger)menu,yousummonthePreferenceswindow.Ithaseightpreferencepanes.Thesepagesdescribetheoptionsoneachpane.
TheFactoryDefaultsbuttononeachpanesetstheoptionsinthatpanetotheLateNightSoftwaredefaultvalues.
Allchangestopreferenceoptionstakeeffectimmediately—exceptfortheAppleScriptFormattingsettingsintheFonts&Colorspreferences,whichhavetobesetwiththeApplybutton(becauseinthiscase,you’retalkingtoAppleScript,nottoScriptDebugger).
FurtherDetails:
Preferences:GeneralPreferences:EditorPreferences:TextSubstitutionPreferences:Fonts&ColorsPreferences:ExecutionPreferences:DictionaryPreferences:KeyBindingsPreferences:SoftwareUpdate
Menus Windows
ScriptDebuggerHelp>Reference>Preferences> TableofContents
Preferences:General
TheGeneralpreferencespanecollectsanumberofoptionshavingmostlytodowithScriptDebugger’sstartupbehaviorandhowScriptDebuggeropensandsavesscriptfiles.
OnStartup:
Rememberopenscripts
Ifchecked,thenwhenScriptDebuggerquits,allopenscriptsarerememberedandwillbereopenedautomaticallythenexttimeScriptDebuggerstartsup.
Createnewscriptifnothingelseisopen
Ifchecked,thenwhenScriptDebuggerstartsup,ifnootherwindowopens,anewscriptwindowwillbecreated.
OnReopen:
Createnewscriptifnothingelseisopen
Ifchecked,thenwhenScriptDebuggergetsaReopeneventwhennowindowisopen,anewscriptwindowwillbecreated.AReopeneventissent,forexample,whenyouclickonScriptDebugger’sDockicon(butnotwhenyoupressCommand-TabtoswitchtoScriptDebugger).
ForNewDocuments:
ShowTemplateChooser
WhenyouchooseFile>NewScriptorFile>NewScriptTab,ScriptDebuggerwillbehaveasifyouhadchosenFile>NewScriptFromTemplateorFile>NewScriptTabFromTemplate,presentingthetemplatechooser.
Usetemplate
WhenyouchooseFile>NewScriptorFile>NewScriptTab,ScriptDebuggerwillusethetemplatelistedhereasthedefaultbasisforthenewscript.
ChooseTemplate
Thisbuttonsummonsthetemplatechoosersothatyoucanpickadifferenttemplatetobethedefaultbasisfornewscripts.
OpeningDocuments:
OpeninTabs
Ifchecked,thenwhenanexistingscriptisopened,itwillbedisplayedinatabinthefrontmostscriptwindowifthereisone.Otherwise,itwillbedisplayedasaseparatescriptwindow.
Asthenotebeneaththischeckboxexplains,youcanholdShiftwhileopeningascripttoreversethisbehavioronaparticularoccasion.So,forexample,ifthecheckboxischeckedandyouopenascriptwhileholdingShift,thescriptwillbedisplayedasaseparatescriptwindow.
Warnwhenapplicationsmaybelaunched
Ifchecked,thenwhenScriptDebuggerbeginsopeningascriptfilethatmightcauseAppleScripttolaunchantargetedapplication,itputsupa“LaunchApplications?”dialog.
Alwaysopenastextwithoutlaunchingapplications
Ifchecked,thenwhenScriptDebuggerbeginsopeningascriptfilethatmightcauseAppleScripttolaunchantargetedapplication,ScriptDebuggeropensthescriptastextifpossible—thusbypassingAppleScriptaltogetherandsopreventingthetargetedapplicationfromlaunching(andsothereisno“LaunchApplications?”dialog).AppleScriptmaystillsubsequentlylaunchthetargetedapplicationifyoulatercompilethescript.
Name:
Yourname.Thisentryisusedtoexpand[[name]]or[[user]]expansiontagsinclippings,templates,andthecopyrightstring.
Organization:
Yourname.Thisentryisusedtoexpand[[organization]]or[[org]]expansiontagsinclippings,templates,andthecopyrightstring.
BundleIDPrefix:
StringtobeusedbydefaultasthestartofthebundleIDforscriptbundles;ScriptDebuggerwillcombinethisprefixwiththescript’sname.Byconvention,theidentifierstartswithcom.andisstructuredlikeareverseURLhostname.Youshouldsetthisprefixtosomethinglikelytobeuniquetoyourself,sothateveryappletyoucreatewillhaveauniqueidentifier.
CopyrightNotice:
CopyrighttexttoappearintheFinder’sGetInfowindowforscriptbundles.Bydefault,ScriptDebuggerderivesthecopyrightstringforanappletfromthistext.Youcanuseexpansiontagshere;theresultisdisplayedbelowthetextfield.
MacOSSettings:
Respondtoapplescript://URLsinwebpages
Theapplescript:URLschemepermitsahyperlink(inawebbrowser,aPDFdocument,andsoforth)tocontainAppleScriptcode,tobedisplayedbyascripteditorapplicationwhenthelinkisclicked.(Thescripteditorapplicationdoesnotautomaticallyrunthecode,asthatwouldbeasecurityviolation.)Bydefault,theprotocolsendsitsmessagestoApple’sScriptEditor,andAppleprovidesnointerfaceforchangingthistarget.ThischeckboxisprovidedsothatyoucanswitchtheroutingoftheprotocoltoScriptDebugger.
DefaulteditorforOSAscripts,applets,anddroplets
MacOSdeterminesfromadocument’sfilenameextensionwhatapplicationopensthefile.Thischeckboxletsyouassociatetherelevantfilenameextensions(.scptandsoon)withScriptDebugger.(ItalsocausesScriptDebuggertobetheeditorthatrespondstotheEditbuttoninanapplet’sruntimeerrordialog.)
Intheory,youcouldaccomplishthesamethingbychoosingScriptDebuggerintheDefaultScriptEditorpop-upmenuofApple’sownScriptEditor’spreferences.
RestoreSuppressedAlerts
SomewarningdialogsinScriptDebugger,suchastheRemoveAllBreakpointsdialog,containa“Donotshowthismessageagain”checkbox,whichyoucanchecktosuppressthatwarningdialogfromthenon.ClickRestoreSuppressedAlertstouncheckthosecheckboxes,sothatallwarningdialogsappearonceagain.
Preferences:Editor
ScriptDebuggerHelp>Reference>Preferences> TableofContents
Preferences:Editor
TheEditorpreferencespanecollectsanumberofoptionshavingmostlytodowithScriptDebugger’sbehaviorasyoutype,aswellascertainappearancesettingsinscriptwindowsandotherwindows.
EditingOptions:
Auto-indent
Ifchecked,thenwhenyoucreateanewlineinascriptwindowbytypingReturn,orpastetextintoascriptwindow,itsindentationwillmatchtheindentationoftheprecedingline.Otherwise,thenewmaterialwillstartattheleftedgeofthewindow.(AppleScriptwillindentproperlyinanycasewhenthescriptiscompiled.)
Auto-pairdelimiters([{""}])
Ifchecked,turnsonScriptDebugger’sauto-pairingfeature.
Wrapselectionwithdelimiters
Ifchecked,thenwhenyoutypealeftdelimiterwhenthere’saselection,thepaireddelimiterswraptheselection(ratherthanhavingtheleftdelimiterreplacetheselection).
Auto-closeAppleScriptblocks(endtell,etc.)
Ifchecked,turnsonScriptDebugger’sauto-closingfeature.
ReferenceapplicationsbyIDwhenpastingTellblocks
Ifchecked,thenwhenScriptDebuggerperformsitsPasteTellbehaviortocreateatellblocktargetinganapplication,theapplication’sbundleid(suchasid"com.apple.finder")isusedintheoutermosttellblock,ratherthanitsname.
Thiswayofspecifyinganapplicationhastheadvantagethatitdoesn’trequiretheapplication’snametoremainconstant(orthatyoustatethenamecorrectly),andthatitwillthrowanerror(whichyoucantrap)ratherthangenerateAppleScript’sdreaded“Whereis…?”dialog.
PasteObjectReferencesasnestedTellblocks
Ifchecked,thenwhenpastinganobjectreference(suchasyoumightobtainbycopyingfromanoutliner),what’spastedisanestoftells.Ifunchecked,what’spastedisasinglelineofofs(thoughofcoursetheoutermostreferencetotheapplicationitselfwillstillbeatellblock).
UsepropertiesforCocoatermsincompletion,clippings
Ifchecked,AppleScriptObjCcodeinsertedbycodecompletionandclippingsisrefactored.
Option-clickopenstermsinDash
Ifchecked,Option-clickinganAppleScriptlanguagetermoranObjective-CCocoatermlooksupthatterminDash,ifyouhaveitinstalled.
Synchronizesplit-viewappearance
Ifchecked,thenchangingaviewsettinginasplitviewpanechangesthesamesettingfortheotherpanesofthesamescript.HolddowntheOptionkeyasyouchangeaviewsettingtoreversethebehaviorfromyourpreferencehere.
Synchronizesplit-viewselection
Ifchecked,thenselectinginonesplitviewpaneselectsthesametextintheotherpanes.
Balanceincludesenclosing([{}])delimiters
Ifchecked,thenthebalancecommandselectseverythingincludingthedelimiterssurroundingthestartingselection;otherwise,itselectseverythingenclosedbythedelimiterssurroundingthestartingselection.
Auto-hiliteopening([{whentypingclosing}])
Ifchecked,thenwhenyoutypearightdelimiter,thecorrespondingleftdelimiterismomentarilyhighlighted(andifthereisn’tone,ScriptDebuggerbeeps).
Hilitedelay
Setsthelengthoftimeduringwhichthemomentaryhighlightingispresent.
Scrollifnecessary
Ifchecked,ScriptDebuggerwillscrollbackwardsifneededtorevealthehighlightedleftdelimiter.
Highlightblockswhenmousehoversingutter
Ifchecked,nestedblocksareshadedandselectablebyhoveringthemousetotheleftofascript.
Showcompiledstateingutter
Ifchecked,uncompiledscriptsdisplaystripesinthegutter.
TableOfContentsOptions:
Sorttableofcontentsmenualphabetically
Ifchecked,thetableofcontentspop-upmenuissortedalphabetically.Otherwise,itsorderistheorderinwhichthingsappearinthescript.HolddowntheShiftkeywhilesummoningthetableofcontentsmenutoseeitsortedintheorderoppositetoyourpreferencehere.
Shownavigationbarlocationwhenscrolling
Ifchecked,thenasyouscrollascriptwindow,atooltipappearsshowingthelinenumberofthelinecurrentlyappearingatthetopofthewindow,alongwithothernavigationbarinformationaboutthatline.
NewLineCharacter:
Setstheline-endcharacterthatistypedinascriptwhenyoupresstheReturnkey.
TabWidth:
Setsthenumberofspacestowhichatabcharactershouldbeequivalent.Thisishowfaranestedblockisindentedinacompiledscript,howfaraparttabstopsare,andhowmanyspacesatabcharacterisconvertedtowhenyouchooseEdit>Entab.
Edit>CommentInserts:
SetsthestringprefixedtothestartofeachselectedlinebytheEdit>Commentcommand.AppleScriptcommentscanstartwith--or#.
Preferences:General Preferences:TextSubstitution
ScriptDebuggerHelp>Reference>Preferences> TableofContents
Preferences:TextSubstitution
TheTextSubstitutionpreferencepaneiswhereyoumanagetextsubstitutions.Ifsubstitutionisturnedon,thenwhenyoutypeanenabled“Replace”columnentryfollowedbyanon-wordcharacter(suchasaspaceoraReturn),thecorresponding“With”columnentrywillbesubstitutedforit.
Textsubstitutionsusethesameexpansiontagsasclippings.Thus,thetextinsertedthroughatextsubstitutioncancontainplaceholders,ofwhichonemayinitiallybeselected.
TextSubstitutions:
Enabled
Ifchecked,thesubstitutionfeatureisturnedon.
Import/Export
Thesebuttonspermitexchangeoftextsubstitutionsbetweenthispreferencespaneandatextfilein.plistformat.
On
Whetheranindividualabbreviationisenabled.
Replace
Theabbreviationyouenterinyourscript.Double-clicktoedit.
With
Thesubstitutionthatwillreplacetheabbreviationinyourscript.Double-clicktoedit.
PlusButton
Addanewabbreviation.
MinusButton
Removetheselectedabbreviation.
SearchField
Filterthelistofabbreviations.BoththeReplacecolumnandtheWithcolumnaresearched.
Preferences:Editor Preferences:Fonts&Colors
ScriptDebuggerHelp>Reference>Preferences> TableofContents
Preferences:Fonts&Colors
TheFonts&Colorspreferencespaneprovidesoptionshavingmostlytodowithscriptformattingandtextsizes.
EditorColors
Background
Thebackgroundcolorofthetextareaofscriptwindows,andoftextviewsofexplorers(i.e.,SourceviewandAEPrintview).
InsertionPoint
Thecoloroftheflashinginsertionpointcursorinascript.
Selection
Thecoloroftheselectedstretchoftextinthetextareaofscriptwindows,andoftextviewsofexplorers.
TabStops
Thecoloroftheverticallinesmarkingtabstops,ifvisible.
InsertionLineHighlight
Thehighlightcoloroftheentirelinecontainingtheinsertionpointinascript.Thelineishighlightedaslongastheselectiondoesnotincludeanyend-of-linecharacters.Thecheckboxtogglesthisfeatureoffcompletely.
CurrentLineHighlight
Thehighlightcoloroftheentirelinethat’sabouttobeexecutedindebugmode.Thecheckboxtogglesthisfeatureoffcompletely.
ErrorLineHighlight
Thehighlightcoloroftheentirelinemarkedasthelocationofanerror.Thecheckboxtogglesthisfeatureoffcompletely.
Multiplecolorscanbeoverlaidononeanother(becausealinemightbehighlightedformultiplereasons,includingbeingselected);that’swhythehighlightcolorsallhavesometransparencybydefault.Feelfreetoexperiment,butifyouaccidentallymakeyourscriptsillegible,clicktheFactoryDefaultsbuttontorevertthem.
AppleScriptFormatting:
Thepretty-printingofcompiledscriptsisprovidedbyAppleScript(aspartofthedecompilationprocess),notbyScriptDebugger.ThispartoftheFonts&ColorspreferencepanethusaccessesAppleScript’spreferences.
YoucanselectasinglelineandsummontheFontsorColorsdialogtochangeitssetting;or,selectmultiplelinesofthetableandsummontheFontsorColorsdialogtochangetheirfontorcolorallatonce.
ChangesarenotsenttoAppleScriptuntilyouclicktheApplybutton.Whenyoudo,anycompiledscriptsthatareopennow,aswellasanycompiledscriptfilesthatyouopenorcreateinthefuture,willtakeontheformattingyouhavespecified.Tocancel(changingyourmindwithoutapplyingyourchanges),switchtoanotherpane,orclosethewindow.
Applycolortomethodandhandlernames
Ifchecked,ScriptDebuggerwilldetectintelligentlytermsthatarenamesofObjective-CmethodsandAppleScripthandlers,andwillapplythiscolortothem(ratherthanthecolorthatAppleScriptwouldapply,whichfailstodistinguishsuchtermsfromvariables).
PlainTextFormatting:
ThefontandcolorofplaintextinexplorersthatisnotformattedasdecompiledAppleScript.Forexample,AEPrintviewisjustplaintext,sothispreferenceappliestoit.Similarly,astringinBestviewisplaintext—butthesamestringinSourceviewisanAppleScriptliteral.
FontSizes:
Outliners/Inspectors
Thetextsizeinoutlinersandvariousscriptwindowinspectorsandpanessuchastheclippingspane.
EventLog
Thetextsizeintheeventlog.
Preferences:TextSubstitution Preferences:Execution
ScriptDebuggerHelp>Reference>Preferences> TableofContents
Preferences:Execution
TheExecutionpreferencespanecollectsanumberofoptionshavingtodowithScriptDebugger’sbehaviorwhenrunninganddebuggingscripts.
ExecutionOptions:
Pausescriptwhenexternaldebuggingbegins
Ifchecked,thenwhenexternaldebuggingstarts(thatis,ascriptsavedindebugmodestartstoruninsomeothercontext),ScriptDebuggerwillpausebeforethefirstexecutablelineofthescript.
Restoreactiveapplicationwhenstepping/continuing
Ifchecked,thenwhenyouresumeexecutionafterapause,theapplicationthatwasactivebeforethepauseisbroughttothefront(unlessthescriptisbeingcontrolledfromScriptDebugger’sDockmenu).
Showexpressiontooltips
Ifchecked,thenwhenyouhoverthemouseovertextinascriptwindow,theAppleScriptexpressionunderthemousewillbeevaluatedanditsvalueshowninatooltip.Insomecases,itwillhelptoselectthedesiredexpressionfirstandthenhoverthemouseoverit.
Foryoursafety,ScriptDebuggerpreventsevaluationofanexpressionifevaluatingittakesalongtimeormighthavemajorsideeffectslikedeletingoralteringanobject(suchanexpressionwillgeneratenotooltip).
Tooltipdelay
ThedelaybetweenthetimewhenthemousehoversoveranAppleScriptexpressionandthetimewhentheexpressionisevaluated.
Showonlywhiledebugging
Ifchecked,thenthesetooltipsappearonlywhenthescriptispausedindebugmode.
Includetellcontext
Ifchecked,thenifthereisatellcontext,itisincludedatthestartofthetooltip(asintheillustration—ifthisoptionwerenotchecked,everythinguptothecolonwouldbeabsent).
BringScriptDebuggertoforegroundwhenscriptspause
Ifchecked,thenwhenpausingindebugmode,ScriptDebuggercomestothefront.
BringScriptDebuggertoforegroundwhenscriptsend
Ifchecked,thenanytimeascriptfinishesexecuting,ScriptDebuggercomestothefront(unlessthescriptisbeingcontrolledfromScriptDebugger’sDockmenu).
Showresultwhenscriptspauseorend:
Thequestionhereiswhatshouldhappenwithregardtothedisplayoftheresultwhenaresultisproduced(unlesstheresultisalreadyvisible).
Thechoicesare:
No
Nothinghappens.
ShowResultInspector
Theresultpaneappears(alongwiththevariablespaneandsoon).
ShowResultBar
Theresultbarappears.
ShowResultExplorerWindow
Theresultisshownasaseparateexplorerwindow.
HideEventLogwindowsondeactivate
Ifchecked,eventlogwindowsarehiddenwhenScriptDebuggerisinthebackground.
HideExplorerwindowsondeactivate
Ifchecked,explorerwindowsarehiddenwhenScriptDebuggerisinthebackground.
ScriptErrorActions:
BringScriptDebuggertoforeground
Ifchecked,thenScriptDebuggercomestothefrontwhenitputsuparuntimeerrordialog.Otherwise,ScriptDebuggerbouncesthenotificationiconintheDock.
Beep
Ifchecked,thenScriptDebuggerbeepswhenitputsuparuntimeerrordialog.
Preferences:Fonts&Colors Preferences:Dictionary
ScriptDebuggerHelp>Reference>Preferences> TableofContents
Preferences:Dictionary
TheDictionarypreferencespanecollectsanumberofoptionshavingtodowiththeappearanceandbehaviorofdictionarywindowsandexplorers.
Opening:
Governswhatshouldhappenwhenyouopenadictionary.Theissuehereisthatadictionarywindowhasthreepossiblestates,sowhichoneshouldappearwhenthewindowopens?Yourchoicesare:
ShowDictionary
Thedictionarywindowdisplaystheterminologylistandtheinfopane.
ShowObjectModel
Thedictionarywindowdisplaystheobjectmodeldiagramandtheinfopane.
ShowExplorer
Thedictionarywindowdisplaystheapplicationexplorer.
Rememberstate
Thestatethatappearsisthestatethatwasshowingwhenthedictionarywindowforthisapplicationwasclosedpreviously.
DictionariesListOptions
Largeiconsindicaterunningapplications
Ifchecked,theninsomeplaceswherethedictionarieslistappears(thedictionarywindow,theFile>OpenDictionarymenu),runningapplicationiconsandtheScriptingAdditionsiconarelarge.
OnlysearchApplicationsfolderfordictionaries
Ifchecked,thenwhenScriptDebuggerpopulatestheAllsectionofitsdictionarieslistatlaunchtime,itdoesn’tlookoutsidetheApplicationsfolder.ApplicationsthatScriptDebuggersubsequentlymeetsforotherreasons(becausetheyarerunning,orrecent,orbecauseyouopentheirdictionaries)willbeaddedtothelistaswell.Dependingonhowyourharddiskisorganized,thiscanreducetheoverallsizeofthedictionarieslist.
ExplorerOptions:
Showcontentsoflistandrecordvalues
ControlshowoutlinersdisplaytheValuecolumnforlistsandrecords.ifchecked,thevalueisaliterallistsimilartoSourceview;ifunchecked,thevalueisshownastheitemcount(e.g.,“listof2items”).
Showdescriptiontooltips
Ifchecked,atooltipappearswhenthemouseishoveredovertheElement/Propertycolumnofanoutliner,displayingthecommentfromthecorrespondingdictionaryentry.
Showvaluetooltips
Ifchecked,atooltipappearswhenthemouseishoveredovertheValuecolumnofanoutliner,displayingthecommentfromthecorrespondingdictionaryentryforthatvalue’sclassifthereisone.
RenderHTMLstringvaluesasHTMLpage
Ifchecked,thenBestviewforanHTMLstringisrenderedasinaWebbrowser.
ShowNelementsatatime
Thenumberofelementstobeshowninitiallyinanoutlinerwhentheelementsofanelementcollectionaredisplayed.Ifthereareadditionalelements,aShowMorebuttonappears.LimitingthenumberofelementsdisplayedatatimereducesthenumberofAppleeventsthatScriptDebuggermustsend.
AccessElementsbyIndex/ID/Name
Thedefaultspecifierforinitiallyaccessingelementsofanelementcollectionfordisplayinanoutliner.Youcanchangethespecifierwiththepop-upmenuintheoutliner.Iftherequestedspecifierfails(becausetheapplicationdoesn’trespondtoit),ScriptDebuggerautomaticallyfallsbackonadifferentspecifier.
DictionaryCaching:
Cachegenerateddictionaries
Ifchecked,ScriptDebuggermaintainscachedcopiesofapplicationdictionaries.Thismakesdisplayandsearchingofdictionariesfaster,becauseoneanapplication’sdictionaryhasbeencached,thereisnoneedtolaunchthatapplicationinordertoobtainitsdictionary.Mostusersshouldnotneedtouncheckit.
ClearCache
ClearsScriptDebugger’sinternalcacheofknownapplicationdictionaries.
Concerningwhyyoumightwanttouncheck“Cachegenerateddictionaries”,orwhyyoumightwanttoclickClearCache,readhere.
Preferences:Execution Preferences:KeyBindings
ScriptDebuggerHelp>Reference>Preferences> TableofContents
Preferences:KeyBindings
ScriptDebuggerpermitsyoutocustomize(change)thekeyboardshortcutforanymenuitem,includingClippingsandScriptsmenuitems.TheKeyBindingspreferencespaneiswhereyoudothat.
KeyBindings:
ThetablelistsallofScriptDebugger’smenusandmenuitems,inhierarchicaloutlineformat.Byclickingthedisclosuretriangles(orbydouble-clickingaline),drilldowntothemenuitemwhosekeyboardshortcutyou’dliketoalter.
Tochangeakeyboardshortcut:
ClicktheSetbutton,ordouble-clickthemenuitemlisting.TheKeystrokedialogopens.
WiththeKeystrokedialogshowing,typeakeyboardshortcut.ItmustinvolveatleasttheCommandkeyortheControlkey,orbeaFunctionkey(F1,F2,etc.,plusHome,PageUp,andsoon).Itmayadditionallyinvolveanycombinationofmodifierkeys(Shift,Control,Option,Command).ScriptDebuggerwarnsyouifyoutypeakeyboardshortcutthatisalreadyinusebyanothermenuitem.
WhiletheKeystrokedialogisshowing:
Toremoveanexistingkeyboardshortcut:
ClickClear.
Toundoyourchangedkeyboardshortcut:
ClickRevert.
Toadoptyournewkeyboardshortcut:
ClickOK.
Tobackoutofthedialogwithoutmakinganychanges:
ClickCancel.
Toremoveanexistingkeyboardshortcutfromamenuitem,sothatthatitemhasnokeyboardshortcut,selectitandclickClear.ThisisthesameasopeningtheKeystrokedialogandclickingClearandthenOK.
Preferences:Dictionary Preferences:SoftwareUpdate
ScriptDebuggerHelp>Reference>Preferences> TableofContents
Preferences:SoftwareUpdate
TheSoftwareUpdatepreferencepaneletsyouspecifywhetherScriptDebuggershouldperiodicallygoonlinetocheckforamorerecentversionofitself,andifso,howoften.
CheckAutomatically
Ifchecked,SoftwareUpdatewillrunperiodically.Optionsinthepop-upmenuforhowoftenSoftwareUpdateshouldrunareDaily,Weekly,andMonthly.
AutomaticallyDownloadandInstallUpdates
Ifchecked,thenwhenSoftwareUpdatedetectsanupdate,itwilldownloadandinstallitwithoutfirstpresentingadialog.
CheckNow
RunSoftwareUpdaterightnow.Thisallowsyoutocheckwithoutwaitingfor,orevenenabling,automaticchecking.
Preferences:KeyBindings
ScriptDebuggerHelp>Reference> TableofContents
Windows
ScriptDebugger’swindowtypesmaybecategorizedasfollows:
Scriptwindows
Dictionarywindows
Explorerwindows
Eventlogwindows
ThePreferenceswindow
FurtherDetails:
Toolbar
Preferences Glossary
ScriptDebuggerHelp>Reference>Windows> TableofContents
Toolbar
Thetoolbaratthetopofawindowcontainscontrolsrelevanttothefunctionalityofthatwindow.
NOTE:Wheretwodifferenttoolbarsareshowninthefollowingillustrationsforakindofwindow,thoseareinfacttwodifferenttoolbars(correspondingtodifferentstatesoftheassociatedscript),andarecustomizedseparately.ThetoolbarsmayalsocontainfewerbuttonsinLitemode.
Thetoolbaratthetopofascriptwindowcontainscontrolsforrunninganddebuggingthescript,andforswitchingbetweenthesetsofpanes.
Thetoolbaratthetopofadictionarywindowcontainscontrolsforswitchingbetweenviews,forreloadingtheselectedentry,foractivatingorquittingthetargetapplication,andsoon.
Thetoolbaratthetopofaneventlogwindowcontainscontrolsforclearingthelog,andforrunninganddebuggingthescript.
Thetoolbaratthetopofanexplorerwindowcontainscontrolsforreloading,and,iftheexplorerwindowwasspawnedfromascriptwindow,forrunninganddebuggingthescript:
Theimportantthingtoknowabouttoolbarsisthattheycanbehiddenandthattheycanbecustomized.
Toshoworhideatoolbar:
ChooseView>ShowToolbarorView>HideToolbar(it’sthesamemenuitem).
Or,Control-clickthetitlebarandchooseShowToolbarorHideToolbar.
Ingeneral,thefunctionalityinatoolbarisavailablealsofrommenus,sofeelfreetohidethetoolbarifyouwanttoconservescreenspace.However,sometoolbarcontrolsarenotavailableelsewhere.Forexample,theSearchfieldinthedictionarywindowtoolbar,andthetimerinthescriptwindowandeventlogwindowtoolbar,havenoalternativeselsewhereintheinterface.
Tocustomizeatoolbar:
ChooseView>CustomizeToolbar.
Or,Control-clickthetitlebarandchooseCustomizeToolbar.
ThisbringsuptheCustomizeToolbardialog,whereyoucandeterminewhatcontrolsappearinthetoolbar.EvenwithouttheCustomizeToolbardialog,youcanCommand-draganiconinatoolbartochangeitspositionorremoveitfromthetoolbar.Yourchangesapply(immediately)tothetoolbarsofallwindowsofthesametype.Thus,customizingthetoolbarofascriptwindowcustomizesthetoolbarsofallscriptwindows,andcustomizingthetoolbarofadictionarywindowcustomizesthetoolbarsofalldictionarywindows.
Youcanalsosettheiconstyleandsizeofatoolbar:
BringuptheCustomizeToolbardialog;itcontainsiconstyleandsizecontrols.
Or,Control-clickinthetitlebar;thecontextualmenugivesyouthesamechoices.
MakingtheiconssmallerandchoosingtheIconOnlystylesavesamaximumamountofscreenrealestatewithoutsacrificinganytoolbarfunctionality.
ScriptDebuggerHelp>Reference> TableofContents
Glossary
Thissectionconsistsofaseriesofshortpagesexplainingsomewordsandconceptsusedinthishelpdocument.
FurtherDetails:
Glossary:AppleScriptObjCGlossary:BundleGlossary:BytecodeGlossary:CodeSignGlossary:CompiledScriptFileGlossary:DictionaryGlossary:ForkGlossary:LibraryScriptGlossary:IconFileGlossary:ObjectModelGlossary:ScriptingAdditionGlossary:SdefGlossary:TellContextGlossary:UseStatement
Windows FrequentlyAskedQuestions
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:AppleScriptObjC
AppleScriptObjC(shortfor“AppleScript/Objective-C”)isalinguisticbridgebetweenAppleScriptandanyObjective-Cframeworksinstalledonyourcomputer:
In/System/Library/Frameworks
In/Library/Frameworks
Inyouruser~/Library/Frameworks
Inascriptbundle,inContents/Frameworks
Whenyousayuseframeworkwiththenameofaninstalledframework,AppleScriptisabletocallintothatframeworkandreceiveareply,eventhoughtheframeworksexpecttobespokentousingObjective-C,notAppleScript.
FrameworksthusprovideawayfordeveloperstopackageObjective-Cfunctionality,andconstituteanalternativetoscriptingadditions.Moreover,therearemanyAppleframeworksalreadypresentonyourcomputer—mostnotably,theCocoaframeworks(in/System/Library/Frameworks).
TIP:Codecompletionafterframework"producesalistofCocoaframeworkscommonlytargetedbyAppleScriptObjC.
Thismagicismadepossiblethroughtwosortsofbridging:
AppleScripttypesarebridgedtoObjective-Ctypes.Forexample,AppleScripttextisbridgedtoObjective-CNSString.
AppleScriptfunctioncallsaremungedtobecomeObjective-Cmethodcalls(orCfunctioncalls).Forexample:
setstocurrentapplication'sNSString'sstringWithString:"testing"
istheequivalentofthisObjective-Ccode:
[NSStringstringWithString:@"testing"];
UsingAppleScriptObjC,youcaneasilydothingsthattakeadvantageofCocoa’spowerbutthatwouldbedifficultorimpossiblein“pure”AppleScript.Forexample,Cocoahassupportforregularexpressions.Inthisexample,weuseregularexpressionstoremovefromastringeverythingthatisn’tanalphabeticalcharacteroraspace:
useframework"Foundation"setsto"This,truly,isatest!"setsstocurrentapplication'sNSString'sstringWithString:ssetrtocurrentapplication'sNSMakeRange(0,ss's|length|)setregextocurrentapplication'sNSRegularExpressionSearchsetsstoss'sstringByReplacingOccurrencesOfString:¬"[^\\p{Letter}]"withString:""options:regexrange:rsetstossastext--"Thistrulyisatest"
ScriptDebuggerhelpsyouwriteAppleScriptObjCcodeinanumberofways:
Objective-Cvaluesaredisplayedcoherentlyinanexplorer,suchastheresultpane.Forexample,thefinalvalueofssintheprecedingscriptisshownas(NSString)"Thistrulyisatest".
ThissortofthingworksformanyObjective-CobjecttypescorrespondingtoAppleScripttypesthathaveaBestviewpresentationinanexplorer.
ForotherObjective-Cobjecttypes,Sourceviewprovidestheoptimalpresentation:effectively,itshowstheobjectdescriptionasitwouldbeloggedtoXcode’sconsole.
Codecompletionworks.
Numerousclippingsareprovided,underthehierarchicalASObjCfolder.Forexample,thisstringisenteredbytheclippingASObjC>MakeObjects>makestring:
settheStringtocurrentapplication'sNSString'sstringWithString:theString
wheretheStringisaplaceholderbothtimes.
ScriptDebuggerhelpsyourefactoryourAppleScriptObjCcodetomakeitneater.
WARNING:AsApplehasexpresseditintheAppleScriptreleasenotes,“UsingObjective-CframeworksfromAppleScriptprovidesmanynewandexcitingopportunitiestocrashthehostprocess.”Oneverygoodwaytocrashistoignoreissuesofthread-safety.SomeCocoamethodsmustbecalledonthemainthread.Anapplet’scoderunsonthemainthread,butaScriptDebugger(orScriptEditor)scriptdocumentrunsonabackgroundthread,inwhichcasemaintainingthreadsafety(bycallingperformSelectorOnMainThread:withObject:waitUntilDone:whereneeded)isuptoyou.
Glossary:Bundle
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:Bundle
Abundle(orpackage)isafilesystementityinmacOSwhosekeycharacteristicisthatalthoughitisadirectorylikeafolder,itisportrayedintheFinderasafile.Bundlesareusefulbecausetheycancontainfilesandfoldersinsidethemwhichtheuserdoesn’tseeorevenknowabout.Infact,theuserisgenerallyunconsciousofthefactthatabundleisabundle.Togiveasimpleexample,macOSapplicationsarebundles.
OpeningabundleintheFinderbydouble-clickingitislikeopeninganapplicationordocument—notlikeopeningafolder.Ifyouwanttoopenabundleasafolder,Control-clickthebundleintheFinder,andchooseShowPackageContentsfromthecontextualmenu.
Insideacompiledscriptbundleorapplication,whenyouShowPackageContents,isaContentsfolder.InsidethatisaResourcesfolder.Thatiswhereyoucankeepadditionalfilesthatneedtotravelwiththebundle.Butyoudon’thavetodothatfromtheFinder,becauseScriptDebugger’sbundleinspectordisplaysthecontentsoftheResourcesfolder,andletsyoumodifythem.
AcompiledscriptbundleorapplicationcanrefertoafileinsideitsResourcesfolderusingthepathtoresourcescriptingadditioncommand.
TheResourcesfoldercancontainaScriptLibrariesfolder,andanyscriptinthatfolderisthenfoundautomaticallyasalibraryscript.
IfyouputansdeffileinsidetheResourcesfolder,youcangiveyourscriptorappletadictionaryandmakeitscriptablebywayofAppleScriptterminology.
IfyouputaniconfileinsidetheResourcesfolder,youcangiveyourappletacustomicon.
Ifyoudon’tknowthepurposeofafileorfolderinsidetheResourcesfolderorelsewhereinthebundle,don’ttouchit!Doingsocandestroytheviabilityofthebundle.
Glossary:AppleScriptObjC Glossary:Bytecode
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:Bytecode
AppleScriptcodeiscompiledintobytecode.Thismeansthat,roughlyspeaking,thenounsandverbsoftheoriginaltextaretranslatedintoasortofcompressed,codedequivalent,calledtokens.ThesetokensaremeaningfultotheAppleScriptruntimeengine(andillegibletoeveryoneelse).Theruntimeengineinterpretsthebytecodeinrealtimeasthescriptruns,parsingwhatevertokensitmeetsalongitspathofexecution,accumulatingthemintochunks,andtranslatingthesechunksfurther,asnecessary,inordertoexecutethem.
Theimplicationforyou,theAppleScriptprogrammer,isthatinitscompiledform,ascriptisillegible.Sowhyareyouabletoreadacompiledscriptfile?It’sbecauseAppleScriptdecompilesthebytecode,translatingthetokensbackintotheirEnglish-likeform.Ifthescripttargetsanapplication,thisdecompilationrequirestheapplication’sdictionary.
Thisisonereasonwhythingscangowrongwhenyouattempttoopenacompiledscript.(ScriptDebuggermaybeabletohelpinsuchasituationbylettingyouopenthescriptastext.)
It’salsowhy,insomecases,AppleScriptmustlaunchanapplicationbeforeitcanshowyouaformattedscript.
Andit’swhythelineationorexactwordingofyourAppleScriptcodeissometimeschangedwhenyoucompileit.
Actually,acompiledscriptfilecontainsnotonlybytecodebutalsosomefurtherinformation(suchasvariablenames)neededtodecompilethetokens.Inarun-onlyscript,thisfurtherinformationisnotpresent,whichiswhythescriptcannotbedecompiled(andthereforecannotbereadbyahumanbeing).
Glossary:Bundle Glossary:CodeSign
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:CodeSign
MacOScomeswithGatekeeper,amechanismthatcanalerttheuserthatastrangeapplicationisbeinglaunchedforthefirsttime.A“strange”applicationisonethatarrivesfromoutside—forexample,theuserreceiveditviaemailordownloadeditwithabrowser—andthatdidnotcomefromtheMacAppStore.
Tomakeiteasierfortheusertotrustastrangeapplication,theapplicationcanbecodesigned.Thisconstitutesaguaranteethat:
TheapplicationwaswrittenbyadeveloperregisteredwithApple.
Thecontentsoftheapplicationhavenotbeentamperedwith;theyareidenticaltowhatthedeveloperintended.
Anappletisanapplication.Therefore,itissubjecttoGatekeeper’soversight.IfyouhaveamembershipwiththeAppleDeveloperProgram,youmightwishtocodesignyourapplet.
NOTE:TheusercanlaunchyourappletevenifitisnotcodesignedbyControl-clickingtheappletintheFinderandchoosingOpenfromthecontextualmenu.Theuserneedstodothisonlyonce;thereafter,theapplicationcanbelauncheddirectlyinthenormalway.However,unlesstheuseralsomovesthefile,undermacOS10.12andlatertheappletwillbelaunchedasifresidentonarandomlynameddiskimage.
Gatekeeper’soversightextendsfurther:itwillnotletyouopenanapplicationfromanunknowndeveloperinanyscripteditor.YouneedtoopenitintheFinderasabovefirst.
Beforeyoucancodesignanapplet,yourkeychainmustcontainaDeveloperIDApplicationcertificateandyoumusthaveApple'sXcodedevelopmentapplicationinstalledinyour/Applicationsfolder.Tocodesigntheappletwhileeditingit:
Inthebundleinspector,chooseyourcertificatenamefromthepop-upmenu.
Or,intheFile>CodeSigningmenu,chooseyourcertificatenamefromthehierarchicalmenu.
Torestrictsigningtorun-onlyexports,checktheExportonlycheckbox.
Thecertificatenameshouldbeginwith“DeveloperIDApplication:”.
Codesigningisobviouslythelastpartofthesavingprocess.Ifsigningfailsforsomereason,youwillendupwithanunsignedapplet(andadialogwillinformyouofsuch).
WARNING:Acodesignedapplethasitspersistentglobalvariablesswitchedoff(asifyouhaduncheckedScript>PersistentProperties).Thisisbecausethesavedstateofthescriptmustnotchange;ithastomatchthecodesigningchecksumthatguaranteesitsintegrity.Whenyouturnoncodesigningforyourapplet,ScriptDebuggerwillpresentadialogwarningyouaboutthis.Ifyourscriptdependsuponitspropertiesmaintainingstateafterquitting,itwon’tworkasacodesignedapplet.
Glossary:Bytecode Glossary:CompiledScriptFile
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:CompiledScriptFile
ThefundamentalAppleScriptfileformatisthecompiledscriptfile.Itconsistsofbytecode,nottheoriginaltext.Italsocanmaintainotherinformation,suchasthepersistentvaluesoftop-levelentities(mostlyproperties,globals,andscriptobjects)andcertaincontextinformation.Acompiledscriptfilecanbeexecuteddirectly,withverylittledelay,becausethereisnoneedtocompilebeforehand—thescriptisalreadycompiled.Manyenvironmentsthatcanrunscriptsexpectacompiledscriptfile.
Acompiledscriptcanhavedifficultyopeningifarequiredapplicationorscriptingadditionismissing.IfthescriptwassavedwithScriptDebugger,youmaystillbeabletoopenthescriptastext.
Glossary:CodeSign Glossary:Dictionary
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:Dictionary
AppleScript’srealpowerandpurposeliesincommunicatingwithscriptableapplicationsandscriptingadditions.TheseprovidepowersthatAppleScriptitselflacks.Inorderthatyou,theAppleScriptprogrammer,mayharnessthepowersofascriptableapplicationorscriptingaddition,ascriptableapplicationorscriptingadditionextendsthevocabularyofthebasicAppleScriptlanguage.Thisextendedvocabulary,belongingtoaparticularapplicationorscriptingaddition,iscalleditsterminology.Adictionaryisthemeansbywhichascriptableapplicationorscriptingadditionletsyou(andAppleScript)knowaboutthisterminology.
Thedictionarytranslatesbetweentwoformsofterminology—theEnglish-liketerms,whichyouuseinyourscript,andtherawAppleeventcodes,whichAppleScriptusestoconstructAppleeventswhencommunicatingwithascriptableapplication.
WhenyouwriteascriptusingEnglish-liketerms,thedictionaryisusedtotranslatethemintorawAppleeventstobesenttoscriptableapplications.
Inacompiledscriptfile,therawAppleeventsareencodeddirectlyintothebytecode.Inordertoopenthecompiledscriptfileanddecompileit,thedictionaryisusedtotranslatetherawAppleeventsbackintoEnglish-liketerms.ThisiswhyAppleScriptmayhavetroubleopeningascriptintheabsenceofarequireddictionary.
Atanygivenmomentinascriptthereareseveralsetsofterminologyvisibleatonce—variablenamesusedinthescript,termsfromthedictionaryofthetargetedapplication,termsfromscriptingadditions,termsfromAppleScript’sowndictionary.Ifthescriptchoosesitstermsunwisely,orifthevisibledictionariesusethesameterminologyindifferentways,terminologyclashcanoccur.Terminologyclashcanresultinascriptthatwon’tcompileorrun,orascriptthatbehavesmysteriously.
ScriptDebuggerhelpsyoutrackdownterminologyclashbylettingyoudeliberatelyviewrawAppleeventcodesinyourscript,intheeventlog,inoutliners,andindictionaries.
Also,youcansearchforterminologyinallvisibledictionariesatonce;thiscanhelptrackdownterminologyclashaswell.
Undercertaincircumstances,acompiledscriptmayopenbutdisplaysomeofitsrawAppleeventsinsteadoftheEnglish-liketerminology,evenwhenyouhavenotelectedtoseetherawcodes.Thiscanhappenbecauseascriptingadditioncouldn’tbefound,orbecauseofsomeproblemwithanapplication’sdictionary;onewayoranother,theunderlyingdictionaryinformationneededtoconvertbytecodebackintoEnglishterminologyismissing.
Ifyouuseanapplicationthatallowsthedictionarytobeextendedthroughplug-ins(suchasQuarkXPressorInDesign),readthediscussionofScriptDebugger’sdictionarycachingmechanism.
Note:Anapplet,orascriptbundleusedasalibraryscript,canhaveadictionary(byputtingansdefintothebundle).
Glossary:CompiledScriptFile Glossary:Fork
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:Fork
IntheearliestdaysoftheMacintoshfilesystem,anarchitecturewasdevisedwherebyafilecouldhavetwopieces,thedataforkandtheresourcefork.Thedataforkwasasinglething,andwasjustfordata(likethetextofaTeachText/SimpleTextfile).Theresourceforkwasforsecondaryinformation,andcouldcontainmanyresources,accessiblebycategoryandnameornumber,asinakindofminiaturedatabase(so,forexample,styleinformationinaTeachText/SimpleTextfile).
WhenOSXwasintroduced,Appleundertookaconcertedefforttodeprecatetheresourcefork,becauseitwasn’tastandardUnixfilesystemthing.Aspartofthiseffort,anewformatforcompiledscriptfileswasdevised,wherethebytecodewaskeptinthedataforkinsteadoftheresourcefork.
Ironically,Applesubsequentlyrealizedthatresourceforkswereagoodthing(becausetheyprovideaplacetoputfilemetadata)andreversedcourse,modifyingthefilesystemsothatafilecanhavemultipleextraforks.Forksarenowcalledextendedattributes.Thelscommand-linetoolwilllistafile’sextendedattributesifyouincludethe@switch,andthexattrcommand-linetoolwilldisplaythecontentsofafile’sextendedattributes.
Noteveryfilesystem,andnoteveryformofcopying,understandsextendedattributes,socertainactions,suchasmovingascripttoaWindowsmachineandbackagain,canstripofftheresourcefork.
Foraplaincompiledscriptfile,ScriptDebuggerstoressomesecondaryinformationinthefile’sresourcefork.Inabundleformatfile,however,noresourceforksareused;secondaryinformationissavedinseparatefiles.(Thedescriptionissavedinan.rtfdfile,therecoverytextissavedinan.rtffile,andtheothersecondaryinformationissavedina.plistfile.)Forthisreason,abundleformatfileisthemostcompatiblewithversioncontrolsystems,non-Macfilesystems,andsoon.
NOTE:Appletsthatarecodesignedcannotincludefileswithresourceforks.ScriptDebuggerwillstripthemoutaspartofthesigningprocess.
Glossary:Dictionary Glossary:IconFile
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:LibraryScript
Alibraryscript(orsimplyalibrary)isacompiledscriptlocatedinoneoftheseplaces:
Theuser’shome~/Library/ScriptLibrariesfolder.
Thetoplevel/Library/ScriptLibrariesfolder.
Inacompiledscriptbundleoranapplicationbundle,insidetheResourcesfolder(displayedinScriptDebugger’sbundleinspector),inafoldercalledScriptLibraries.
Theadvantageofplacingascriptinoneofthesespeciallocationsisthatitcanbeloadedbyanyotherscriptusingitsnamealone.
NOTE:ThisAppleScriptfeaturewasintroducedinmacOS10.9(Mavericks).AppleScriptactuallylooksforlibraryscriptsinsomeadditionallocations,butyouareunlikelytousethem,andthelisthasvariedineachsubsequentsystem.
Forexample,suppose~/Library/ScriptLibrariescontainsacompiledscriptfileHello.scpt,likethis:
propertygreeting:"Hello"propertygreetee:"World"ongreet()displaydialoggreeting&","&greetee&"!"endgreet
Thenanotherscriptcansay:
tellscript"Hello"setitsgreetingto"Howdy"greet()endtell
Thephrasescript"Hello"isasufficientreferencetoHello.scpt,becauseitislocatedinoneoftheScriptLibrariesfolders.
That,however,isnotthecanonicalwayofreferringtoalibraryscript.LibraryscriptsaremostcommonlyusedinconjunctionwithAppleScript’susestatement,andScriptDebuggerexpectsandrecommendsthatyouusetheminthatway(andsodoesApple).Thus:
useHello:script"Hello"tellHellosetitsgreetingto"Howdy"greet()endtell
TIP:ScriptDebugger’scodecompletionfeaturecanhelpyouenteralibraryscriptreference.Ifyouaskforcodecompletion(pressEsc)withthecursorbetweenthequotesinscript"",ScriptDebuggerpopsupalistofavailablelibraryscriptsforyoutochoosefrom.
Thelibraryscriptfeatureessentiallysupersedestheoldloadscriptmechanism.(Youcanstilluseloadscript:youspecifyascriptfilebyitspathname,loaditwithloadscript,receiveascriptobject,andsendmessagestothatobject.)
EditingaScriptandaLibraryScriptTogether
Youwilloftenwanttoeditalibraryscripttogetherwithamainscriptthattargetsthelibraryscript,andthenrunthemainscripttotestit.ScriptDebuggerishappytoletyoudothis,andevenhelpsyoubymakingiteasytoopenthelibraryscriptfromwithinthemainscript:puttheselectionintoascript"MyScript"lineandchoseFile>OpenScriptLibrary“MyScript”.
However,youarenowinatrickysituationbecauseofAppleScript’sinternalcachingmechanism.Ifyoumakeachangeinthelibraryscript,savethechangedlibraryscript,andthenjustrunthemainscript,themainscriptwillbeunawarethatthelibraryscripthaschanged—itwon’treloadit,becauseithascachedit.Thesolutionistoremembertorecompilethemainscriptbeforerunningit.
Glossary:IconFile Glossary:ObjectModel
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:ObjectModel
Ascriptableapplication’sworldofobjectsconstitutesitsobjectmodel.Here’showitworks.
Ascriptableapplication’sdictionarydefinesclasses,roughlycomparabletothetypesof“thing”thatconstituteitsworld.Forexample,iTunesdefinesaplaylistclassandatrackclass;theFinderdefinesafolderclassandafileclass.Classescanhavepropertiesandelements,whosevaluetypecanbeaclass.Thus,intheory,foragivenapplication,thereisahierarchicalcontainmentrelationshipamongstitsclasses.Forexample,iniTunes,aplaylist“has”tracks,andintheFinder,afolder“has”files.
Intheory,thisrelationshipcanbeexpressedasa“tree”,ahierarchicalstructurestartingwiththeapplicationitself,andcontainingeveryobjectintheapplication.Indeed,thistreeisvitaltoyouruseofAppleScripttocommunicatewithascriptableapplication,becauseitiswhyyouareabletorefertoanobjectinthefirstplace.Forexample,youcanspeaktotheFinderoffile1offolder"MyFolder"becausetheFinder“has”foldersandafolder“has”files.
Thistreeoftheobjectsthatyoucanrefertoistheapplication’sobjectmodel.
ScriptDebuggerexposesanapplication’sobjectmodelinthreeforms:
Inadictionarywindow,theobjectmodeldiagramshowsyoutheapplication’scontainmenthierarchyasatree.
Inanexplorer,anapplication’sactualobjectsaredisplayedhierarchicallythroughanoutliner.
InthePasteTellhierarchicalmenuitem,andinanexplorerwindow’stitlebar,theobjectmodelofarunningapplicationappearsashierarchicalsubmenus.
Isay“intheory”becauseinrealitythingsarenotsosimple.Thecontainmenthierarchyisdescribingwhat’spossible,notwhat’sreal,andthereforeinfiniterecursionsandcircularitiescanresultwhenyoutrytoexpressitasasimpletree.Forexample,intheFinder,inreallifetherecouldneverbeaninfinitedepthoffoldercontainment.Inthecontainmenthierarchydiagram,however,youcankeepopening“folder”entriestoget“folder”entriesinsidethem,andsoon,foreverandever(oruntilyougetbored),justbecauseasatheoreticalmatter,it’salwaystruethatafoldercancontainafolder.Ifthisconfusesyou,andyou’dratherseetheobjectmodelasitexistsinreality,usetheapplicationexplorer.
Glossary:LibraryScript Glossary:ScriptingAddition
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:ScriptingAddition
Ascriptingadditionisacompiled-coderesourcethatimplementsadditionalAppleScriptlanguageterminologyandcommands.AppleScriptloadsanyscriptingadditionsthatitfindsintheScriptingAdditionsfolder(in/System/Library,in/Library,orinyouruserLibrary),andthetermsandcommandsimplementedinthembecomeeffectivelypartofthelanguage.
Becauseofthenatureofthismechanism,youdon’thavetobeinanyapplication’stellcontextinordertouseatermdefinedbyascriptingaddition.Instead,ascriptingaddition’stermsaresimply“partofthelanguage”.Forexample,tolearntoday’sdate,youjustsaycurrentdateanywhereoutsideanyapplicationtellcontext.Youdonot—indeed,youcannot—explicitlytargetaparticularscriptingaddition.
Nevertheless,everythinginAppleScriptworksthroughdictionaries,soeveryscriptingadditionhasadictionary.ScriptDebuggercollectsallthedictionariesofallloadedscriptingadditionsintoasingledictionarydisplay,called“ScriptingAdditions”.
Becausescriptingadditionterminologyisalwaysavailable,nomatterwhatapplicationyouaretalkingto(orevenifyouaretalkingtonoapplication),ScriptDebuggermakesscriptingadditiontermsautomaticallypartofthetellcontext.Forthisreason,scriptingadditionsareanotorioussourceofterminologyclash.
However,youcanmitigatethisissuebyajudiciousapplicationofusestatements.Itturnsoutthatifanyusestatementappears,scriptingadditionsbecomeunavailableunless:
Theyaregivenausestatementoftheirown:
usescriptingadditions
Or,theyareusedwithinanexplicitusingtermsfromscriptingadditionsblock.
Thelatterstrategyhastheadvantagethatitavoidsmakingallscriptingadditionterminologyglobaltothescript.
Runningascriptintheabsenceofascriptingadditiononwhichthescriptdependswillprobablyresultinamysteriousruntimeerror.OpeningsuchascriptwillresultintheappearanceofrawAppleeventcodesinthescript(ScriptDebuggertriestohelptrackdownthesourceoftheproblem,butitisn’teasybecausethenameofthemissingscriptingadditiondoesn’tappearinthecode,sincescriptingadditionsarenotexplicitlytargeted).
Glossary:ObjectModel Glossary:Sdef
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:Sdef
Ansdeffile(pronounced“ess-deaf”,andstandingfor“scriptingdefinition”)isafilecontainingascriptingdictionary.Many,butnotall,applicationsincludetheirdictionariesthisway,asdoscriptbundlesthatprovideterminology.
Regardlessofhowanapplicationprovidesitsdictionary,ScriptDebuggertranslatesthedictionaryintosdefformatasthebasisofitspresentationofdictionaryinformationandforcachingpurposes.
ScriptDebuggercanalsoopenansdeffiledirectly,andwillpresentitsdictionarywindowasifyouhadopenedascriptableapplication.Thisisintendedasanaidifyou’redevelopingoreditingansdef.
Ifyouuseanapplicationthatallowsthedictionarytobeextendedthroughplug-ins(suchasQuarkXPressorInDesign),readthediscussionofScriptDebugger’sdictionarycachingmechanism.
NOTE:Explaininghowtowriteansdeffileforabundleisbeyondthescopeofthisdocumentation;watchWWDC2013video416togetstarted.
Glossary:ScriptingAddition Glossary:TellContext
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:TellContext
Thelinguisticconstructioncommonlyusedtoperformcommunicationwithascriptableapplicationisthetellblock.Forexample:
tellapplication"TextEdit"activatesetword1ofdocument1to"Hello"endtell
Inthatcode,theindentedlinesarewithinatellblocktargetingTextEdit.Thus,TextEditistheirtellcontext.
Nestedtellblockscanworktheirwaydowntheobjectmodelhierarchytonarrowthetellcontextstillfurther.Forexample:
tellapplication"TextEdit"activatetelldocument1setword1to"Hello"endend
Inthatcode,thesetline’stellcontextisdocument1ofTextEdit.
ScriptDebuggerwatchesasyouwork,andknowswhatthetellcontextofthecurrentselectionorinsertionpointis.ThisknowledgeisfundamentaltocertainScriptDebuggerfeatures.Forexample:
Thetellcontextinspectorexplorestheelementsandpropertiesofthetargetedapplicationrelativetothecurrenttellcontext.
Thedictionariesinspectorcansearchinthecurrenttellcontext.So,ifyouselect“word”intheabovecodeandchooseSearch>LookUpDefinition,andifthedictionariesinspectorsearchoptionsaresettoSearchinTellTarget,ScriptDebuggerwillsearchforthetermwordinTextEdit’sdictionary.
TheFile>OpenXXXDictionarymenuitemknowswhatdictionarytoopenbasedonthetellcontext.
Thetellcontextitselfmaydependuponthevalueofavariableatagivenmoment.ScriptDebuggerhandlesthissituationcorrectly,thoughtheresultsmaysurpriseyou.Forexample:
ondoTell(x)tellapplicationxgetwindow1endtellenddoTelldoTell("Finder")
Supposethisscriptispaused(indebugmode)atthelinegetwindow1.Whatshouldthetellcontextbeifweclickinthatline?Well,therearetwostackframes:thedoTellhandlercall,andthetoplevelofthescript(theimplicitrunhandler).InthestackframeofthedoTellhandlercall,xhasavalueandthereisatellcontext(theFinder).Butinthestackframeofthetoplevelofthescript,xhasnovalueandthereisnotellcontext(andthetellcontextinspectorwillreport“noselectedtellblock”).Sothetellcontextdependsupontheselectedstackframeaswellasthecurrentselection.
Glossary:Sdef Glossary:UseStatement
ScriptDebuggerHelp>Reference>Glossary> TableofContents
Glossary:UseStatement
TheAppleScriptusestatementhasthefollowinguses:
MakinganApplication’sTermsGlobal
Auseapplicationstatementcausesthatapplication’stermstobecomeglobal.Forexample,insteadofthis:
tellapplication"Finder"getdesktopendtell
Youcansaythis:
useapplication"Finder"getdesktop
Butdon’tsaythat!Makinganapplication’stermsglobalisareallybadidea.There’sagooduseforuseapplicationdescribedlateronthispage.
LinkingtoaCocoaFramework
AuseframeworkstatementlinkstoaCocoaframework,thusincorporatingCocoaclassesandtheirObjective-Ccommands.YourscriptcannowspeakAppleScriptObjC.Forexample:
useframework"Foundation"setstocurrentapplication'sNSString'sstringWithString:"thecatsatonthemat"setarrto(s'scomponentsSeparatedByString:"")asstring
LoadingaLibraryScript
Ausescriptstatementloadsalibraryscript:
usescript"Hello"
However,thetop-levelentitiesintheloadedscriptdonotbecomegloballyavailable;youstillneedatellblocktoaccessthem.Thus,itismorecommon(andcanonical)toprovideanidentifier,asdiscussedinthenextsection.
Butifthescripthasadictionary,ausescriptstatementdoesmakeitsterminologygloballyavailable(likeanapplication).
ProvidinganIdentifier
Anidentifierfollowedbyacoloninausestatementspecifyinganapplicationorascriptturnstheidentifierintoasynonymforthatapplicationorscript.Youcanthentargettheidentifierwithatellblock(oritsequivalent).Forexample:
useHello:script"Hello"tellHellosetitsgreetingto"Howdy"greet()endtell
RequiringaVersion
Withaversionparameter,useapplescript,useapplication,andusescriptcanforcethescripttofailiftheversionisnotatleastashighasrequested.Forexample:
useAppleScriptversion"2.5"--won'trunonsystemsearlierthanmacOS10.11(ElCapitan)useapplication"Finder"version"10.10.5"withoutimporting--won'trunonsystemsearlierthanmacOS10.10.5(Yosemite)--notethe"withoutimporting"!preventstheterminologyfrombecomingglobaluseHello:script"Hello"version"1.1"--won'trunwithoutlibraryscript"Hello"version1.1orhigher
TIP:Togivealibraryscriptaversionnumber,saveitasacompiledscriptbundleandsetitsversionnumberinthebundleinspector.
LoadingScriptingAdditions
Ifanyusestatementappears,scriptingadditionsbecomeunavailableunless:
Theyaregivenausestatementoftheirown:
usescriptingadditions
Or,theyareusedwithinanexplicitusingtermsfromscriptingadditionsblock.
Thelatteristoberegardedaspreferable,asitavoidsmakingallscriptingadditionterminologyglobaltothescript.
Glossary:TellContext Glossary:VersionBrowser
ScriptDebuggerHelp>Reference> TableofContents
FrequentlyAskedQuestions
Thissectionprovidesanswerstosomequestionsthatweretootechnicalortoomiscellaneoustoincorporateintothemaindiscussion.
Note:Byitsverynature,informationinthissectionmaybevolatile.Forthelatestfacts,checkatLateNightSoftware’swebsite.
FurtherDetails:
What’sInstalledWhere?WhatarePersistentProperties?WhereAretheLibraries?What’sTheBigDealWithLineEndings?WhyDoApplicationsOpenSpontaneously?Hey,ScriptDebuggerChangedMyFormatting!HowDoIScriptScriptDebugger?
Glossary
ScriptDebuggerHelp>Reference>FrequentlyAskedQuestions> TableofContents
What’sInstalledWhere?
ScriptDebuggerisagoodmacOScitizen,anddoesnotheedlesslyinstallfilesinplaceswhereit’snotsupposedto.Still,itdoesinstallfilesinavarietyoflocations,andyoumightwishtoknowwheretheseareandwhatthefilesdo.Sohere’salist.
~/Library/Components
ScriptDebuggerinstallsScriptDebugger.componenthere.Thisfileimplementsdebugging,bymeansofanOSAlanguage.(InApple’sScriptEditor,youwillseethisOSAlanguagelistedasAppleScriptDebugger.)
~/Library/Caches/ScriptDebugger
ScriptDebuggermaintainscachesofapplicationdictionarieshere.ThesecachesmeanthatScriptDebuggercanopenandaccessdictionariesmuchmorequickly.
~/Library/ApplicationSupport/ScriptDebugger7
ScriptDebuggerkeepsvariousspecial-purposefoldershere:
TheClippingsfolderiswhereyoucanstoreclippingsfilesthatScriptDebuggercanaddtotheClippingsmenuandtheclippingsinspector.Anyfilesfoundherewillappearatthetopofmenuandinspector,separatedfromtheapplication-providedclippings.
TheScriptsfolderiswhereyoucanstorescriptfilesthatScriptDebuggercanaddtotheScriptsmenu.Anyfilesfoundherewillappearatthetopofmenuandinspector,separatedfromtheapplication-providedentries.
TheTemplatesfolderiswhereScriptDebuggerlooksforusertemplatestobelistedinthetemplatechooser.
YoucanopenthesefoldersintheFinderbychoosingtherelevantcommandsfromtheScriptsmenu.
Note:Beforeversion7ScriptDebuggerwouldautomaticallypopulatethesefolderswithasetofscriptsandclippings,butnowitmaintainsuneditableversionswithintheapplicationbundle.Ifyouwishtouseamodifiedversionofaclipping,youcancopyitacrosstoyourlibrarybychoosingScripts>ImportClippings.Youcantheneditthecopyasyouwish.
~/Library/Preferences
ScriptDebuggerkeepsonepreferencefilehere,com.latenightsw.ScriptDebugger7.plist.Thiscontainsalotofinformation,includingstateinformationforvariouswindows,sobeawarethatifyouremovethisfile,suchinformationwillbelost.
WhatarePersistentProperties?
ScriptDebuggerHelp>Reference>FrequentlyAskedQuestions> TableofContents
WhatarePersistentProperties?
WhenascriptissavedwithScriptDebugger,thecurrentvaluesoftop-levelpropertiesandglobalscanbesavedalongwithit,sothattheyarestilltherewhenthescriptisopenedagainlater.ThisfeaturemaybetoggledonoroffbycheckingoruncheckingScript>PersistentProperties.
WhenyouopenacompiledscriptwithScriptDebugger,andifScript>PersistentPropertieswascheckedatthetimescriptwassaved,thevaluesoftop-levelentitiespersistfromthelasttimethescriptwasexecuted.Theyarenotreinitializedtotheirbasevaluesuntilthenexttimethescriptiscompiled.(Merelyrunningascript,withoutchangingit,doesnotcompileit.)
So,forexample,ascript’stop-levelpropertygreetingmightbedefinedas"howdy",butitmightnotactuallybe"howdy"whenyoustartrunningthescript(unlessyoucompilethescriptfirst),becausegreeting’svaluemighthavebeenchangedtosomethingelse(typicallybythescriptitselfasitranlasttime),andthechangedvaluewillpersist.ScriptDebuggershowsyouwhatthevaluereallyis,inthevariablespane.
Note,however,thatApple’sScriptEditorstripsthesevalueswhenitopensascript(becauseitrecompilesthescript).Thus,ifyousomuchasopenthisscriptwithScriptEditor,thepersistentvalueisstrippedout,sonowwhenthescriptisrun,greetingisreinitializedto"howdy".
Note:IfAppleScriptrefusestosaveyourcompiledscript,generatinga“StackOverflow”error,thecausemightbeanAppleScriptbugconnectedwithpersistenttop-levelvalues.Forcethescripttorecompiletodeletethepersistenttop-levelvalues,andtrysavingagain.
Therearecertaincontextswherepersistentpropertiesareabadidea.That’swhyScriptDebuggergivesyoutheabilitytotogglethisfeatureoffforanindividualscript.Examplesofplaceswhereyoushouldgenerallynotusepersistentpropertiesare:
Codesignedscripts.Tohelpyouwiththis,ScriptDebuggerwillturnoffpersistentpropertiesassoonasyouturnoncodesigningforascript.
ScriptsthatuseAppleScriptObjC.Tohelpyouwiththis,ScriptDebugger’sAppleScriptObjCtemplateshavepersistentpropertiesturnedoffbydefault.
ScriptsthatuseGUIscripting.
Scriptsthatinvolveconfidentialinformation,suchaspasswords.
What’sInstalledWhere? WhereAretheLibraries?
ScriptDebuggerHelp>Reference>FrequentlyAskedQuestions> TableofContents
WhereAretheLibraries?
ScriptDebugger5andearlierprovidednativelibrariesasawayofincorporatingotherscriptsintothisscript.Thisfeature,however,isnowsupersededbyAppleScript’sownlibraryscripts.Therefore,thenativelibrariesarenotsupportedinScriptDebugger7.
AScriptDebugger5scriptusingnativelibraries,whenopenedinScriptDebugger7,willappearwithoutthoselibraries.Thenativelibrariesarepreserved,however,andwillstillbepresentifthescriptisopenedagainunderScriptDebugger5.
YouareexpectedtoupdateyourcodetouseAppleScriptlibraryscripts.Therearetwowaystoproceed:
Youcanupdateascriptmanually.Tohelpwiththistask,youcanuseScriptDebugger’sscriptabilitytogetalistofascript’snativelibraries(legacyscriptlibraries,legacyscriptlibraryfiles)andrelevantfeaturesofascript(scriptproperties,scripthandlers).
YoucanuseScriptDebugger’sbuilt-inlibraryconverter.Whenyouopenascriptcontainingnativelibraries,ScriptDebugger7willdetectthisandwilloffertoconvertthemtolibraryscriptsforyou.Thesescriptswillbeplacedinyouruser~/Library/ScriptLibrariesfolder.Ifthiswouldresultinduplicates,you’llbegiventhechoiceofoverwritingorskippinganyduplicateitems.
Afterconversion,thenativelibrariesarestrippedfromthescript.Besuretoexaminethenewlycreatedlibraryscriptsandmakesureyou’rehappywiththem.Ifyou’renot,don’tsavethescriptoritwillloseitsnativelibraries.Ifyou’reindoubt,itmightbewisetostartwithacopyoftheoriginalscriptandperformtheconversionthere.
TechnicalInformationAbouttheBuilt-InConverter
TheconverterworksbylookingforallreferencedScriptDebugger5nativelibraries.Iftherearebrokenaliases,theconversionprocesswillstopanddirectyoutoopenthescriptwithScriptDebugger5andcorrecttheproblemthere.
Asitcreateseachlibraryscript,theconverteraddsacorrespondingusestatementtoyourscript.Inaddition,itaddspropertydeclarationsforanytop-levelentities(suchasproperties)inthelibraryscript;thus,thosetop-levelentitiesbecomeglobaltothisscript.Theresultwillthereforematchthebehaviorofnativelibraries—exceptthatduplicateentitynamesareignored,whereasinScriptDebugger5,youwouldhavebeenwarnedaboutthisissueatcompiletime.
Theconverterisnotrecursive,soifyouhaveanylibrariesthatreferenceotherlibraries,youwillneedtoopenandconvertthembeforeyouconvertthemainscriptthatusesthem.
WhatarePersistentProperties? What’sTheBigDealWithLineEndings?
ScriptDebuggerHelp>Reference>FrequentlyAskedQuestions> TableofContents
What’sTheBigDealWithLineEndings?
AppleScriptmakeslineendingsacomplicatedissue.ScriptDebuggerdoesalottomakethemsimple,oratleasttransparent.Butsoonerorlateryoumayrunintoproblemswithlineendings,sohere’sanexplanation.
Imaginethattwomightyforcesareatwork,tusslingwithlineendings:
TheAppleScriptcompiler.AppleScriptisacompiledlanguage,andthiscompilationinvolvesatransformationperformeddirectlyonyourcode.Yourcodestartslifeasordinarytext,butwhenitiscompiled,yourfilebecomesacompiledscriptfile,andyouareshownthedecompiledbytecode.TheAppleScriptcompilergoesbacktotheearly1990s,atimewhenMacintoshlineendingswereallCR(ASCII13).So,aftercompilation,everycompletelineofcodeinyourcompiledscriptfileendswithaCR.
Unix.MacOSisUnix,andthestandardUnixline-endcharacterisLF(ASCII10).Forexample,ascriptwritteninaUnixscriptinglanguagesuchasPerlorRubyneedstohaveLFlineendingsoritmaynotrunproperly.ManymacOStextapplicationsconformtothisstandardaswell.Forexample,whenyoucreateanewmulti-linefileinTextEditandsaveitasplaintext,thelineendingsareLF.ThisissueisparticularlyacuteinAppleScriptwhenyouusedoshellscript,becauseamulti-linestringintendedfortheUnixshellwillusuallyexpectLFasaline-endcharacter.
So,theAppleScriptcompilerwantsyourlineendingstobeCR,butmacOSwantsyourlineendingstobeLF.Theconflictbetweentheseforcesisalwaysgoingon.Sometimesthisconflictworksbehindthescenes—forexample,theAppleScriptcompilerwillchangeyourlineendingstoCR,nomatterwhattheywerebefore,andthat’sthat.Buttheconflictalsoarisesupfront,everytimeyoupresstheReturnkeywhileyou’retypinginascriptfile.Atthatmoment,somecharacterneedstobeentered,sowhatshoulditbe?
ScriptDebuggerhelpsyoudealwiththisconflict,intwomainways:
Visibility.ScriptDebuggermakesitpossibleforyoutoseeyourlineendings—youcanshowinvisibles.
FreedomofChoice.ScriptDebuggerletsyouchoosewhatcharactertheReturnkeyenters;it’sanEditorpreference(NewLineCharacter).ThefactorydefaultforthispreferenceisLF,andifyoucreateanewmulti-linescriptwiththepreferencesetthisway,andinvisiblesshowing,youcanactuallywatchAppleScriptchangethelineendingsfromLFtoCRwhenyoucompile.
ScriptDebuggeralsoletsyouchoosewhatlineendingsshouldbeusedwhenyousaveascriptastext.This,however,introducesafurthercomplicatingfactor.
TheproblemstemsfromthefactthatinAppleScript,aliteralstringcanspanmultiplelines:
setsto""
Theintegrityoftheline-endcharacterwithinthisstring(whichmightbeLForCR)ispreservedthroughdecompilation,becausebehindthescenesthecompiledscriptisjustbytecode(andthebyteinquestionispartofaliteralstring).Butnowsupposeyouelecttosavethisscriptastext.WhatshouldScriptDebuggerdo?Thecharacterafterthefirst"isalineending.IfyoutellScriptDebuggertosavewithCRlineendingsorLFlineendings,thischaracterwillbecomeCRorLF,respectively,regardlessofwhatitis“really”supposedtobe(thuspossiblyalteringthefunctionalityofyourscript).
ThisiswhyScriptDebuggerprovidestheAsIsoption(thedefault),whichleavesalllineendingsintheresultingtextfilethesameasinyourcompiledscript.Thetotallysafesolution,though,isnottouseanyliterallineendingswithinquotedstrings.Don’tusethe“escaped”literals"\r"or"\n",becausetheAppleScriptdecompilerturnstheseintoactuallineendings.Instead,constructyourstringsincode,generatinglineendingsatruntime(using,forexample,thereturnorlinefeedglobalvariable).Ofcourse,ifyouneversaveastext,thentheissuedoesn’tariseinthefirstplace.
Finally,beawarethatpasting(ordragging)fromatextfileintoascriptcanraiseline-endcharacterissues.Whatispastedistext,whichcanhaveanykindoflineending.ScriptDebuggerdoesnotmagicallyconverttheseasthepasteisperformed.Iftherearemulti-linestringliteralsinwhatispasted,orifthetargetscriptistext,incorrectlineendingsmaynowbepresentinthescript.Again,showinvisibleswillbeagreathelphere.
WhereAretheLibraries? WhyDoApplicationsOpenSpontaneously?
ScriptDebuggerHelp>Reference>FrequentlyAskedQuestions> TableofContents
WhyDoApplicationsOpenSpontaneously?
Whydoapplicationsopenspontaneously?Thetroubleisthatcertainapplicationsmustberunninginordertoprovideadictionary.SoeverytimeAppleScriptneedsthedictionaryofsuchanapplication—notjustinorderforascripteditortodisplayadictionary,butinordertocompileordecompileascriptthattargetsthatapplication—theapplicationmuststartupifitisn’trunning.Sothisisaproblemwiththesystem,andwithhowAppleScriptworks.IthasnothingtodowithScriptDebugger.Infact,ScriptDebuggerdoestwothingstoreducethisbehavior.
NOTE:Tocompileascript,youmustletAppleScriptlaunchanyneededapplications.CompilationissomethingthatAppleScriptdoes,notsomethingthatScriptDebuggerdoes;soScriptDebuggercan’tpreventthisbehavior.
OpeningandDecompilingaScript
WhenyouopenascriptthattargetsanapplicationwhichmustbelaunchedinorderforAppleScripttodecompileit,ScriptDebuggerdetectsthisandoptionally(ifthecorrespondingGeneralpreferenceischecked)presentsadialog:
Youcanproceedtoopenthescript(andallowtheapplicationtolaunch)ifyouwish,butperhapstheoverheadoflaunchinganapplicationjusttoreadascriptseemsunwarranted.IfthisscriptwassavedwithScriptDebugger,itcontainsatextversion,andyoucanclickOpenAsTexttoopenthatinstead.Thusyoucanreadthescriptwithoutlaunchingthetargetedapplication.
Ifthescriptdoesnotcontainatextversion,theOpenAsTextbuttonwon’tappear;youronlychoiceswillbetoopenthescriptandletAppleScriptlaunchBBEdit,ortocancelandnotopenthescriptatall.
OpeningaDictionary
ScriptDebuggermakesheavyuseofanapplication’sdictionary.Forexample,inordertocalculatethetellcontext,ScriptDebuggermustloadthetargetapplication’sdictionary.Thiscouldcausethetargetapplicationtolaunchifitisnotrunning.AndScriptDebuggerneedsthetellcontextwhenyoustarttoopentheFilemenu(becauseoftheOpenXXX’sDictionarymenuitem),sotheremaybeadelayasyouchoosefromtheFilemenu,whilethetargetapplicationlaunches.Andthen,ofcourse,there’sthewholebusinessofwhathappenswhenyousearchthedictionariesofmultipleapplicationssimultaneously.
Thegoodnews,however,isthatthisshouldhappenonlyonceforeachapplication.ScriptDebuggercachesanapplication’sdictionary(in~/Library/Caches/ScriptDebugger)whenitopensthedictionary,providedyouhavenotunchecked“Cachegenerateddictionaries”intheDictionarypreferences.So,aslongastheapplication’sdictionaryandlocationdon’tchange,ScriptDebuggerwon’thavetolaunchthatapplicationagaininordertoaccessitsdictionary.
Notethatthishasnothingtodowiththediscussionunder“OpeningandDecompilingaScript”earlieronthispage.EvenwhenScriptDebuggerhascached(say)BBEdit’sdictionary,AppleScripthasnot,sowhenyouopenascriptthattargetsBBEdit,AppleScriptwillstilltrytolaunchBBEditifitisn’trunning.
However,youcanuncheck“Cachegenerateddictionaries”,orclearthecacheondemandbyclickingtheClearCachebutton,andtherearecertainspecializedcircumstanceswhereyoumightwishtodothis.Inparticular,someapplicationswith'aete'dictionariesallowthosedictionariestobeextendedthroughplug-ins(notableexamplesareQuarkXPressandInDesign).ScriptDebuggerhasnowaytonoticewhenyouaddorremoveaplug-in,sothedictionarythatitdisplays,comingfromthecachedcopy,willbeoutofdate.
Applicationsthatdonotusethisplug-inarchitecturedonotpresentanydifficulties,andareirrelevanthere.Ifyouinstallanewversionofanapplication,ScriptDebuggerwillnoticethatthedictionaryhaschangedandwillautomaticallyrefreshthecachedcopy.
So,ifyouusetheseapplications,itisuptoyoutoremembertoremovethecachedcopyofthedictionaryeachtimeyoualtertheapplicationbyaddingorremovingplug-ins.Therearethreeways,orlevels,fordoingthis:
Uncheck“Cachegenerateddictionaries”.Thispreventscachingaltogether.Applicationswillopenwhenevertheirdictionariesareneeded.
Keep“Cachegenerateddictionaries”checked,butclicktheClearCachebuttonwhenneeded.Youallowcachingtoworknormally,buteveryonceinawhileyouthrowawaythecaches.Somostofthetimeyouaregettingallthebenefitsofcaching.Butyouare
throwingawaythecachesforallthedictionaries,whenonlyonedictionary(QuarkorInDesign)istheproblem.
Throwawaythecacheforjusttheproblematicapplication,manually.Thisisthebestsolution.Here’show:
1. QuitScriptDebugger.
2. Open~/Library/Caches/ScriptDebugger.
3. Findthecacheforyourproblemapplication’sdictionary.
Thestartofthecachefile’snamewillbeeithertheapplication’sname(e.g.“MicrosoftWord7c5d2075.sdef”)oritsbundleidentifier(e.g.“com.apple.mailb521204d.sdef”).
4. MoveittotheTrash.
What’sTheBigDealWithLineEndings? Hey,ScriptDebuggerChangedMyFormatting!
ScriptDebuggerHelp>Reference>FrequentlyAskedQuestions> TableofContents
Hey,ScriptDebuggerChangedMyFormatting!
Sometimesithappensthattheappearanceofyourscriptischangedinwaysyouneverintended.Forexample,youcarefullyusethelinecontinuationcharactertobreakupalonglineofcode,likethis:
setrtodisplaydialog"Whatisyourfavoritecolor?"¬defaultanswer"Blue.No,red!"¬buttons"Aaaaaaaagh!"¬defaultbutton"Aaaaaaaagh!"¬withtitle"ACrucialTest"
Butsuddenlyitappearsbrokenupallincorrectly,likethis:
setrtodisplaydialog¬"Whatisyourfavoritecolor?"defaultanswer¬"Blue.No,red!"buttons¬"Aaaaaaaagh!"defaultbutton¬"Aaaaaaaagh!"withtitle"ACrucialTest"
WhyisScriptDebuggerdoingthistoyou?We’resorrythisishappening,butScriptDebuggerhasnothingtodowithit.It’sa“feature”ofAppleScript.Ithastodowiththefactthatascriptiscompiledintobytecodeandthendisplayedtoyouindecompiledform.Therearesomeannoyingbehaviorsdeepwithinthatround-tripprocess,andthisisoneofthem.There’snothingScriptDebuggercandotopreventit.
ArelatedbehavioristhatalthoughAppleScriptwillletyouuseaterm’ssynonym,itwillalsosometimesreplacethesynonyminthedecompiledscript.So,forexample,closedocument2savingfalseislegal,butitischangedtoclosedocument2withoutsaving(andyouareprobablyfamiliarwiththeexpansionofapptoapplication,reftoareferenceto,andsoforth).
WhyDoApplicationsOpenSpontaneously? HowDoIScriptScriptDebugger?
ScriptDebuggerHelp>Reference>FrequentlyAskedQuestions> TableofContents
HowDoIScriptScriptDebugger?
ScriptDebuggerisscriptable.Moreover,youcanscriptScriptDebuggerfromwithinScriptDebuggeritself,eitherfromascriptwindoworfromascriptintheScriptsmenu.SuchascriptneednotincludeatellblocktargetingScriptDebugger;ScriptDebuggerwillimplicitlybethetelltarget.
However,fordevelopmentanddebuggingpurposesitisbettertosupplyanexplicittellblock(tellapplication"ScriptDebugger"),becauseifyoudon’t,thereturnedvaluesintheresultcouldbelesshelpful.
ScriptDebuggerwillappearamongtheapplicationslistedunderFile>OpenDictionary,inthedictionariesinspector,andinthedictionarywindow,soyoucaneasilyopenitsdictionary.
Thedictionaryisfairlyself-explanatory,soadetaileddiscussionofscriptingScriptDebuggershouldbeunnecessary.Buthereareafewpointsthatdeserveattention.
Note:ScriptsinScriptDebugger’sScriptsmenuarerunbyaseparateprocess,similartothewaythesystemScriptsmenu’sscriptsarerun.
OpeningThings
SomekindsofScriptDebuggerwindowcanbeopened.Herearesomeexamples:
Tocreateanewemptyscriptwindow,saymakenewdocument.
Toopenascriptfromdisk,sayopenalias"vol:folder:file.scpt".Theresultisareferencetothedocument.
Toopenanapplication’sdictionary,opentheapplicationitself.Thesimplestapproachistotakeadvantageofpathtoapplication;so,forexample,open(pathtoapplication"BBedit").
Alternatively,saymakenewdictionarywindow.Thiscreatesanemptydictionarywindow,notdisplayinganyapplication’sdictionary.
Onceyouhaveadictionarywindow,youcanchangewhatapplication’sdictionaryitdisplaysbysettingitsfilespecproperty.Forexample,setfilespecofdictionarywindow1to(pathtoapplication"BBEdit").
Toopenascriptwindow’seventlogwindow,tellthedocumenttomakeneweventlogwindow.Theeventlogwindowandthedocumenthavepointerstooneanother.
Toopenascriptwindow’sresultexplorerwindow,tellthedocumenttoopenlastresult.
Allopenwindowsareelementsoftheapplicationobject.Youcangetacompletelistbyaskingforeverywindow,oryoucangetalistofwindowsinaparticularcategorybyaskingfore.g.everydictionarywindoworeveryscriptwindow.
Everyscriptwindowisassociatedwithexactlyonedocument(ithasadocumentproperty).Thetwoclassesarenotinterchangeable,butascriptwindowanditsdocumenthavethesameid.ThisisfairlystandardCocoaScriptingstuff.
Documentsarenumberedfronttoback,sothenumberingisvolatile.Inotherwords,document1isthedocumentofwhateverscriptwindowisfrontmostatthatmoment.
ClosingThings
Tocloseawindow,usetheclosecommand.
However,whenyourscriptrunningwithinScriptDebuggerwantstocloseascriptwindow(ordocument),youmustprovidethefullformandyoumustnotusethesavingaskoption,orScriptDebuggerwillthrowanerror.So,forexample,youcansayclosedocument2withoutsaving,andyoucansayclosedocument2savingyesifthefilehasbeenpreviouslysaved,butyoucannotsaysimplyclosedocument2,norcanyousayclosedocument2savingask.
Bythesametoken,ifdocument2hasneverbeensaved,youcannotsaysimplysavedocument2.Youmustsupplythefullform,withaninparameterspecifyingwheretosave.
ThereasonisthatwhenScriptDebuggerisscriptingitself,wecannotpausethescriptwhiletheuserinteractswiththe“Doyouwanttosavechanges?”dialogortheSaveFiledialog.Soyoumustavertsuchinteractionbystatingexplicitlywhatyouwantdonewiththedocument.
ManipulatingThings
Asyouwouldexpect,mostinteractionwithobjectsoccursbywayoftheirproperties.Look,forexample,atthepropertiesofadocumentoradictionarywindoworaneventlogwindowtoseeallthemanipulationsyoucanperform.Forexample,toswitchascripttodebugmode,setthedocument’sdebuggerenabledtotrue.
Therearetwowaystomanipulatethecontentsofascript.First,youcangetorsetascript’sentirecontentsastext,throughthedocument’sscriptsourceproperty;youcanalsogetandsetascript’sentirecontentsasascriptobject,throughthedocument’sscriptproperty.
Youcanalsomanipulateascript’sselection.Ifyougetselectionyouarehandedmeretext,butifyouaskforselectionaspointorcharacterrangeofselection,whatyougetisalistoftwointegers,thecharacteroffsetaftertheinsertionpointorthestartoftheselection(thefirstcharacteroffsetis1)andthecountofcharactersintheselection.Similarly,youcansetselectiontoaltertheselectedtext,butifwhatyousettheselectiontoisalistoftwointegers,orifyousetcharacterrangeofselectiontosuchalist,yourepositiontheselection.
So,forexample,here’sacrudebuteffectiveutilityforselectingagivenlineofagivenscript:
onselectLine(num,docnum)tellapplication"ScriptDebugger"telldocumentdocnumsetLtoeveryparagraphof(getscriptsource)setoffsto1repeatwithifrom1to(num-1)setaLinetoitemiofLsetoffstooffs+(lengthofaLine)+1endrepeatsetselectionto{offs,lengthofitemnumofL}endtellendtellendselectLineselectLine(3,2)--orwhatever
RunningScripts
ScriptDebuggerprovidesarepertoryofspecializedcommandsformakingascript(adocument)dosuchthingsascompile,execute,stepinto,andsoon.Executioncausescompilation,obviously.Aftercallinganycommandthatcausescompilation,youcancheckwhethercompilationsucceededbyexaminingthedocument’scompiledproperty.
Someofthesecommandscomewithacaveat:execute,pause,stepinto,stepout,andstepoverallsharethefeaturethattheycanreturnbeforethescripthasstoppedorpaused(andstartrecordingcanreturnbeforethescripthasstartedrecording).ThisisaconsequenceofScriptDebugger’smulti-threadedarchitecture.
Thecorrectapproach,therefore,ifyouwishtoproceedafterthescripthasdonewhatyouaskedittodo,istopollthedocument’sexecutionstateproperty.So,forexample,here’sascriptthatprovidesautilityforwaitinguntilthedocumentispausedorstopped,andshowshowtouseitinconnectionwithexecute.
onwaitUntilReady(d)repeatwhileexecutionstateofdisnotin{stopped,paused}delay0.2endrepeatendwaitUntilReady--andhere'showtouseittellapplication"ScriptDebugger"setdtodocument"convertFigures"telldexecutemywaitUntilReady(d)ifnotcompiledthenreturnlasterrormessage--compilationfailed,geterroriflasterrormessageisnotmissingvaluethen--executionfailed,geterrorreturnlasterrormessageendifreturnlastresult--executionsucceeded,getresultendtellendtell
FutureDirections
We’dliketoprovidefullerscriptability,butthistakeswork,sowewouldprefertogoindirectionsthatouruserswillactuallyuse.IfScriptDebugger’sscriptabilitylacksafeatureyouneed,doletusknow.
Hey,ScriptDebuggerChangedMyFormatting!
TableofContents
HereisacompleteTableofContentsforthishelpdocument.
ScriptDebuggerHelp
OpeningandSavingScripts
Open
TheTemplateChooser
Tabs
Compatibility
OpeningaCompiledScriptasText
Save
Formats
CompiledScript
Application(Apple)
Application(Enhanced)
Text
Run-OnlyScript
WhatIsSaved
FileOwner
SpotlightandQuickLook
Description
Manifest
Bundle
Explore
Dictionary
OpenDictionaryWindow
RunningApplications
RecentandFavoriteApplications
CurrentContext
ScriptingAdditions
OpenAnyDictionaryWindow
OpenMultipleDictionaryWindows
DictionariesInspector
DictionaryWindow
TerminologyList
TypesofEntitiesShownintheTerminologyList
DictionaryInfoPane
Size
Inheritance
ExtraDocumentation
AppleEventCodes
HierarchiesandDiagrams
SearchinDictionary
LookUpDefinition
BackandForward
MiscellaneousDictionaryActions
ApplicationExplorer
TellContextInspector
Explorer
WhereExplorersAppear
ExplorerWindows
Best
Outliner
OutlinerEditing
Source
AEPrint
ExplorerViewOptionsandActions
Develop
Edit
ScriptWindow
ViewOptionsinaScriptWindow
LineWrapping
Invisibles
Spaces
LineNumbers
TabStops
Raw(Chevron)Syntax
DefaultScriptWindowSizeandState
EditingandNavigation
BlockStructure
Auto-Closing
BalanceCommand
BlockShading
CodeFolding
Delimiters
CodeCompletion
TextSubstitution
AppleScriptObjCRefactoring
MiscellaneousTypingandSelection
TellBlocksandTermsBlocks
Clippings
Placeholders
HowClippingsWork
InsertingContent
Shift
Comment
Tab
SplittingtheEditor
Find
GoToLine
Navigate
ExternalEditor
Run
Compile
Execute
TestingHandlers
Result
ScriptTiming
ProgressReporting
Variables
Errors
Leaks
EventLog
EventLogWindow
Record
DefaultTarget
ParentScript
Debug
Pause
HowtoPause
ExecuteWhenDebugging
Breakpoints
TemporaryBreakpoints
ExecutetoHere
BreakpointsInspector
ConditionsandActions
Step
Trace
CallStack
Variables(DebugMode)
Expressions
Exceptions
CodeCoverage
ExternalDebugging
TheMiniDebugger
Reference
Menus
ApplicationMenu
FileMenu
EditMenu
ViewMenu
SearchMenu
ScriptMenu
DictionaryMenu
WindowMenu
ClippingsMenu
ScriptsMenu
Preferences
Preferences:General
Preferences:Editor
Preferences:TextSubstitution
Preferences:Fonts&Colors
Preferences:Execution
Preferences:Dictionary
Preferences:KeyBindings
Preferences:SoftwareUpdate
Windows
Toolbar
Glossary
Glossary:AppleScriptObjC
Glossary:Bundle
Glossary:Bytecode
Glossary:CodeSign
Glossary:CompiledScriptFile
Glossary:Dictionary
Glossary:Fork
Glossary:IconFile
Glossary:LibraryScript
Glossary:ObjectModel
Glossary:ScriptingAddition
Glossary:Sdef
Glossary:TellContext
Glossary:UseStatement
Glossary:VersionBrowser
FrequentlyAskedQuestions
What’sInstalledWhere?
WhatarePersistentProperties?
WhereAretheLibraries?
What’sTheBigDealWithLineEndings?
WhyDoApplicationsOpenSpontaneously?
Hey,ScriptDebuggerChangedMyFormatting!
HowDoIScriptScriptDebugger?
TableofContents