Differences

This shows you the differences between two versions of the page.

--- documentation:Scripting [2016/05/30 06:40] – created peternlewis
+++ documentation:Scripting [Unknown date] (current) – removed - external edit (Unknown date) 127.0.0.1
@@ Line 1: / Line 1: @@
-====== Scripting ======
-===== Executing Scripts =====
-You can execute shells scripts, AppleScripts, JavaScript~~For~~Automation (JXA), JavaScript in Safari or Google Chrome, Swift Scripts, Automator Workflows, or filter the clipboard using BBEdit Text Factories.  You can run a script file or include the script as text directly in the application.
-AppleScripts and shell scripts, JavaScript for Automation and Swift scripts, give you a powerful way of adding new facilities we have not specifically provided for, as well as controlling other applications.  JavaScript enables deep control over a web page.
-Shell scripts can execute any installed scripting language, such as perl, python, ruby or whatever.  Be aware that because shell scripts are executed in a non-interactive shell, typically none of the shell configuration files (like CODE{{{.login}}} or CODE{{{.profile}}}) will be executed, which may change the way the shell script behaves.
-The results of scripts can be displayed, or they can be typed or pasted in to the current selection, or saved into a variable or clipboard.  This allows you to insert text that depends on many factors, such as date calculations, file listings, SQL queries, web pages, or anything else you can imagine.  Alternatively, the results can be displayed in Notification Center, in a window, or in large type across the screen.  Or you can ignore the results, or execute the script asynchronously, leaving it running in the background.
-You can also use the clipboard to pass data between actions.  For example, a script can use pbpaste to read the current clipboard, and pbcopy to set the current clipboard.
-Variables can be accessed from shell scripts via the environment variables in the form $KMVAR‗Variable‗Name where KMVAR‗ is prefixed, and spaces are converted to underscores.  AppleScripts can also access the environment variables using the CODE{{{system attribute}}} command, but note that CODE{{{system attribute}}} is not safe for international characters.
-Note that the total size of the variables stored in the environment is limited to 100K, so larger variables may be excluded to ensure the variables do not take up excessive amounts of environment space since this is limited by the system.
-Variables whose names start with "ENV‗" override regular environment variables (eg "ENV‗PATH" overrides the regular "PATH" environment variable).
-AppleScript can create variables with:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  make variable with properties {name:"Calculation Result", value:"57"}
-end tell
-</code>
-or read and write variables with:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  set kmVarRef to make variable with properties {name:"Calculation Result"}
-  set oldValue to value of kmVarRef
-  set value of kmVarRef to 10
-end tell
-</code>
-or the less AppleScripty way (7.1+) with:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  set oldValue to getvariable "Calculation Result"
-  setvariable "Calculation Result" to 10
-end tell
-</code>
-and JavaScript for Automation (JXA) can access variables with:
-<code javascript>
-var kme = Application("Keyboard Maestro Engine");
-var oldValue = kme.getvariable('Calculation Result');
-kme.setvariable('Calculation Result', { to: 10 });
-</code>
-and delete variables with:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  delete variable "Calculation Result"
-end tell
-</code>
-JavaScript in web browsers can access the variable values by using the document.kmvar dictionary, like document.kmvar.Variable‗Name (spaces are converted to underscores).
-AppleScripts and JavaScript For Automation scripts are executed in the background via CODE{{{osascript}}}.  This means they are not allowed to do user interaction.  You can work around this by asking an application like System Events to do the user interaction for you, for example:
-<code applescript>
-tell application "System Events"
-  activate
-  display dialog "Hello"
-end tell
-</code>
-The CODE{{{osascript}}} tool will execute in 64-bit mode, which may be a problem if you have old versions of AppleScript extensions installed.  However, you can set the command line tool that is used to execute AppleScripts as described in [[Preferences#Other_Hidden_Preferences|Other Hidden Preferences]].
-See also the [[Variables]] section.
-===== Controlling Keyboard Maestro via Scripting =====
-The primary scripting interface to Keyboard Maestro is the Keyboard Maestro Engine’s CODE{{{do script}}} support.  You can ask Keyboard Maestro to:
-* execute a macro by name
-* execute a macro by unique ID
-* execute an action given its XML code
-Note in most cases you must ask “Keyboard Maestro Engine”, not “Keyboard Maestro”.
-The easiest way is to use the name, for example:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  do script "[Name of Your Macro]"
-end tell
-</code>
-The macro must be defined and enabled, and the macro group must be enabled and currently active.
-If there is more than one macro with the same name, you will get an error, so you can use a UID instead of a name.
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  do script "D0C150C7-8A0C-4837-918A-427E2BCFB6B9"
-end tell
-</code>
-The CODE{{{do script}}} will not return until the macro is finished executing.
-You can pass an optional parameter using the CODE{{{with parameter}}} clause, which you can read in the macro as the [[/token/TriggerValue|%TriggerValue% token]].
-You can determine a macro’s UID by selecting it and choosing [[Menus#Edit_Copy_as_Copy_UID|Copy UID command]] in the [[Menus#Edit_Copy_as|Copy as sub-menu]] in the [[Menus#Edit|Edit menu]].
-You can trigger a macro using the kmtrigger: scheme with a URL like `kmtrigger://macro=MacroName&value=Value` (the value is accessible via the %TriggerValue% Text Token).
-An even more powerful way to script Keyboard Maestro is to execute specific actions based on their XML code.  This allows you to construct any action, including changing the action on the fly, without having to create a macro first.  A simple example would be:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  do script "<dict><key>MacroActionType</key><string>SwitchToLastApplication</string></dict>"
-end tell
-</code>
-The easiest way to determine the appropriate XML is to create an example action in an example macro and then export the macro.
-You can read information about the existing macros using the CODE{{{gethotkeys}}} and CODE{{{getmacros}}} commands.  See the Keyboard Maestro Engine AppleScript dictionary for more information.
-You can disable or enable a Macro or Macro Group from AppleScript with:
-<code applescript>
-tell application "Keyboard Maestro"
-  setMacroEnable "Macro/Macro Group Group Name or UID" with/without enable
-end tell
-</code>
-This actually asks the editor to disable or enable the macro or macro group, so the change is both visible and permanent.
-Alternatively you can use the [[/action/Set_Macro_Enable|Set Macro Enable action]].
-You can start editing a Macro or Macro Group from AppleScript with:
-<code applescript>
-tell application "Keyboard Maestro"
-  editMacro "Macro/Macro Group Name or UID"
-end tell
-</code>
-You can ask Keyboard Maestro Engine to reload the macros with:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  reload
-end tell
-</code>
-You can also import macros, get the selected macros, or delete a macro or macro group from AppleScript.  See the Keyboard Maestro AppleScript dictionary for more information.
-===== Enhancing AppleScript =====
-Keyboard Maestro Engine makes several of its facilities available to AppleScript.
-You can ask it to play a sound with:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  play sound alias "Harddisk:System:Library:Sounds:Glass.aiff"
-end tell
-</code>
-You can ask Keyboard Maestro Engine to perform a calculation for you with:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  set n to calculate "JULIANDATE()"
-end tell
-</code>
-You can ask Keyboard Maestro Engine to process tokens for you with:
-<code applescript>
-tell application "Keyboard Maestro Engine"
-  set clip to process tokens "%PastClipboard%3%"
-end tell
-</code>
-===== The keyboardmaestro URL Scheme =====
-Another way you can control Keyboard Maestro us using the keyboardmaestro URL scheme, which supports the following formats:
-* keyboardmaestro://u=support%40stairways.com/s=ABCDEFGH0123456789 – enter your username/serial number.
-* keyboardmaestro://m=Activate%20Application%20Switcher – edit a specific macro or macro group.
-* keyboardmaestro://q=Activate – filter macros with this keyword.
-* keyboardmaestro://g=All%20Macros/q=Activate – select a macro group and filter macros with this keyword.
-* keyboardmaestro://a=Execute – filter actions with this keyword.
-* keyboardmaestro://c=All%20Actions/a=Execute – select action category and filter actions with this keyword.
-See also the [[Calculations]] and [[Text Tokens]] sections.