Add AppleScript Support #867

SKaplanOfficial · 2025-04-05T19:21:52Z

I've added AppleScript equivalents for all of the Shortcuts, plus support for the AppleScript standard dictionary and text suite. The full supported terminology can be viewed via Script Editor's File->Open Dictionary menu or in MarkEditMac/Resources/MarkEdit.sdef

I haven't done much Swift development, so I probably used odd approaches in some places. Let me know if I need to rework anything. Also, I'm not sure why Info.plist got all rearranged — is there something I can do to fix that?

Here's a test script demonstrating what's currently supported:

tell application "MarkEdit"
	-- Create new documents
	set doc1 to make new document with properties {name:"test1.md"}
	set doc2 to make new document with properties {name:"test2.md"}
	set doc3 to make new document with properties {name:"test3.md"}

	-- Modify file content
	delay 0.5
	set source of doc1 to "# Hello, world!

The *quick* brown fox **jumps** over the lazy *dog*.

- Item 1
- Item 2
- Item 3"
	set source of doc2 to "# Testing..."
	set source of doc3 to source of doc2

	set targetDoc to first document whose source contains "dog"

	-- Get rich text details
	set italicWords to words of formatted text of targetDoc whose font contains "Oblique"
	if italicWords is {"quick", "dog"} then
		set targetWindow to first window where its document is targetDoc
		set index of targetWindow to 1

		tell targetDoc
			-- Run JavaScript on documents
			evaluate JavaScript "document.body.style.zoom = '200%'"

			-- Save documents
			set outputPath to POSIX file (POSIX path of (path to downloads folder) & "test1.md")
			close saving in outputPath
		end tell
	end if

	close doc2 without saving
	close doc3 without saving
end tell

Known issues:

Specifying the source property when using the make command raises an error. This is because setting source relies on there being an existing webview to call replaceText on. Current workaround: Use a momentary delay after make, then use set source to ....
The color property of rich text elements is always {0, 0, 0}. This is expected since there is no color information included in the document's source. A future improvement could be to process the markdown source and add colors based on the current theme.

Closes #854.

cyanzhong · 2025-04-06T00:29:35Z

Thank you for the contribution, Stephen!

Regarding the plist change, it looks strange to me too. Can you share the actual changes needed here?

Is it just:

<key>NSAppleScriptEnabled</key>
<true/>
<key>OSAScriptingDefinition</key>
<string>MarkEdit.sdef</string>

cyanzhong · 2025-04-06T00:29:59Z

MarkEdit.xcodeproj/project.pbxproj

 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
 				INFOPLIST_KEY_NSMainStoryboardFile = Main;
-				INFOPLIST_KEY_NSPrincipalClass = "$(PRODUCT_NAME).Application";
+				INFOPLIST_KEY_NSPrincipalClass = MarkEdit.Application;


Is using static name here required?

cyanzhong · 2025-04-06T00:31:39Z

MarkEditMac/Sources/Scripting/EditorDocument+Scripting.swift

+    get {
+      return self.stringValue
+    }
+    set(newValue) {


nit: (newValue) can be omitted.

cyanzhong · 2025-04-06T00:33:24Z

MarkEditMac/Sources/Scripting/EditorDocument+Scripting.swift

+import Carbon
+import MarkEditKit
+
+extension EditorDocument {


Can we name source and formattedText to be more scripting specific? Since we are creating extension that can be used in the entire app.

If these are something to be used in the script, it's fine to keep them clean (or follow some conventions).

Sure, would prefixing them with scripting be enough? E.g. scriptingSource?

cyanzhong · 2025-04-06T00:35:28Z

MarkEditMac/Sources/Scripting/EditorDocument+Scripting.swift

+  /// Executes a user-provided JS script in the document's webview.
+  @objc func handleEvaluateCommand(_ command: NSScriptCommand) -> Any? {
+    guard let inputString = command.evaluatedArguments?["script"] as? String else {
+      let scriptError = ScriptError.missingInput(message: "No JavaScript script provided")


Is this user-facing string? I can localize it later if so.

It would get presented to users as an AppleScript error, but I think it would only occur if the incoming event data gets corrupted, which is very rare. Just omitting the script parameter or supplying a non-text value gets handled by AppleScript before sending any messages to the application.

Maybe it's not worth keeping the message? The error number would still appear anyway.

cyanzhong · 2025-04-06T00:39:14Z

MarkEditMac/Sources/Scripting/EditorDocument+Scripting.swift

+      return nil
+    }
+
+    guard let targetEditor = self.windowControllers.first?.contentViewController as? EditorViewController else {


nit: code convention wise, I prefer to hide self. if we can. I can do a cleanup later.

cyanzhong · 2025-04-06T00:44:19Z

MarkEditMac/Sources/Scripting/NSColor+Scripting.swift

+  static let RGBColorCoefficient: CGFloat = 65535
+
+  /// Unpacks incoming color descriptors into NSColor objects.
+  @objc func scriptRGBColor(with descriptor: NSAppleEventDescriptor) -> NSColor? {


Just curious, are these functions called by scripts? Don't see a caller in the code.

The get called automatically by the Apple Event Manager when users send/receive color objects via AppleScript. They're normally automatically generated at runtime, but that's skipped for colors due to how the text suite defines them.

cyanzhong · 2025-04-06T00:47:03Z

MarkEditMac/Sources/Scripting/NSColor+Scripting.swift

+    }
+
+    return NSColor(
+      calibratedRed: CGFloat(rgbColor.red) / Self.RGBColorCoefficient,


I am not an expert of this, just making sure we are using correct initializer, is calibrated needed?

Not sure, the only clear reference for those methods is iterm2. I think the unpack method can use any NSColor init method, but I'd need to check.

cyanzhong · 2025-04-06T00:49:25Z

MarkEditMac/Sources/Scripting/EditorDocument+Scripting.swift

+//  Created by Stephen Kaplan on 4/2/25.
+//
+
+import Carbon


This is deprecated, does Foundation work?

No, keyASUserRecordFields is only defined under Carbon, but without it, I don't know another way to construct valid NSAppleEventDescriptors for dictionaries with unknown keys, which is needed for handling results from JavaScript evaluation. Apple still uses it in non-archived documentation.

I can use the raw OSType int value instead, which I guess it better.

cyanzhong · 2025-04-06T00:52:24Z

MarkEditMac/Sources/Scripting/ScriptErrors.swift

+    case .noActiveEditor:
+      return -3
+    case .jsEvalError:
+      return -1702


Why -1702?

Good catch, those values were placeholders. Was going to use the OSType of the AS event class instead.

cyanzhong · 2025-04-06T00:54:54Z

Thanks again, Stephen. The change overall LGTM, I just left some comments.

Regarding this:

Specifying the source property when using the make command raises an error. This is because setting source relies on there being an existing webview to call replaceText on. Current workaround: Use a momentary delay after make, then use set source to ....

I couldn't think of a better way either. I used similar delays in the app to handle a similar case (see newFileFromClipboard).

I have one more general question about the change, since MarkEdit only handles plain text, why is rich text support needed?

SKaplanOfficial · 2025-04-06T02:17:57Z

Thank you for the contribution, Stephen!

No problem, it was a fun challenge to tackle!

Is it just:

<key>NSAppleScriptEnabled</key>
<true/>
<key>OSAScriptingDefinition</key>
<string>MarkEdit.sdef</string>

I believe so, but I'll have to make sure. Apple Events are very picky. Won't get the changes done until tomorrow, but I'll respond to your other comments now.

I couldn't think of a better way either. I used similar delays in the app to handle a similar case (see newFileFromClipboard).

Hm, I was thinking about looking into @Observable. If we separate the stringValue and other properties derived from the webview bridge into an observable class, then both EditorDocument and EditorViewController could react to changes more easily, maybe. Could be a big change, so definitely out of scope for this.

I have one more general question about the change, since MarkEdit only handles plain text, why is rich text support needed?

The text suite (which includes the 'rich text' AppleScript class) is the recommended way to access individual words, characters, etc. from AppleScript since repeating over elements is much, much faster in Swift/ObjC, so that's the reason for the additional property in general.

Then it just seemed reasonable to use Swift's markdown support in NSAttributedString so you can detect when text is italic/bold without including the surrounding symbols in the "words" subproperty.

cyanzhong · 2025-04-06T04:51:45Z

I would like to update the wiki after we merge the change and looking for these example:

Getting the content of an opened document
Replacing the selection with some text

Could you please kindly provide some example scripts? Thanks!

cyanzhong · 2025-04-06T09:39:52Z

For the plist change, did you use Xcode to generate the change, or did you modify the plist file directly?

Xcode may re-generate the entire file which may lead to unwanted changes.

SKaplanOfficial · 2025-04-06T15:13:28Z

Made those changes, and added the error message strings to AppResources.Localized.Scripting.

* Replacing the selection with some text

Knew I was forgetting something. Added the selection property in the latest commit.

Made some examples here: https://gist.github.com/SKaplanOfficial/9637cd69e2b21b1749521aafa1f71c95

For the plist change, did you use Xcode to generate the change, or did you modify the plist file directly?

I used Xcode, so that explains it! I've reverted those changes and manually added the ones for AppleScript.

cyanzhong · 2025-04-07T01:30:04Z

MarkEditMac/Resources/MarkEdit.sdef

+
+    <class name="document" code="docu" description="A MarkEdit document." plural="documents" inherits="document">
+      <cocoa class="MarkEdit.EditorDocument"/>
+      <property name="source" code="mdsc" type="text" access="rw" description="The raw markdown source of the document.">


Does this mean the variable name in scripts is source, which uses scriptingSource in code?

Yes, exactly.

cyanzhong · 2025-04-07T01:57:22Z

README.md

 - Fast: edits 10 MB files easily
 - Lightweight: installer size is about 3 MB
- Extensible: seamless Shortcuts integration
+- Extensible: seamless integration with Shortcuts and AppleScript


cyanzhong · 2025-04-07T02:18:08Z

I just tested and it works really well, going to check this in and do some follow-up changes like localization and cleanup, if you don't mind.

SKaplanOfficial · 2025-04-07T02:23:06Z

Sounds good. Let me know if you need anything from me.

cyanzhong · 2025-04-07T12:18:51Z

MarkEditMac/Sources/Scripting/EditorDocument+Scripting.swift

+    }
+
+    // Preserve newlines for better error reporting
+    let jsText = inputString.replacingOccurrences(of: "\\n", with: "\\\\n")


@SKaplanOfficial this quite interesting to me, does this really work?

If we are replacing \n to \\n in the scripts, should it be inputString.replacingOccurrences(of: "\n", with: "\\n")?

I don't quite get why we need double backslashes, and why we need to replace them at all.

Looks like we can remove it. You're right, it doesn't look like it'd work anyway.

When I was testing earlier, the evaluate JavaScript command would report errors as if there were only one line (e.g. line 1, column n where n was the length of the entire string up to that point).

Something fixed that problem, but I don't think it was this.

SKaplanOfficial added 5 commits March 22, 2025 20:32

Add AppleScript standard dictionary support

27ee513

Add 'execute JavaScript' Command

e2b95b2

Add formatted text property and "evaluate JavaScript" command

0ef1cca

Minor fixes

4ade3f6

Minor fixes

1753eb4

cyanzhong reviewed Apr 6, 2025

View reviewed changes

SKaplanOfficial added 3 commits April 6, 2025 09:01

Undo unintended changes in project files

f814c3f

Update error codes, use localizable strings

641de81

Add 'selection' property to sdef

d85d1be

SKaplanOfficial requested a review from cyanzhong April 6, 2025 15:13

cyanzhong reviewed Apr 7, 2025

View reviewed changes

cyanzhong merged commit 461983c into MarkEdit-app:main Apr 7, 2025
1 check passed

cyanzhong mentioned this pull request Apr 7, 2025

Cleanup and localization for AppleScript #872

Merged

cyanzhong reviewed Apr 7, 2025

View reviewed changes

Add AppleScript Support #867

Add AppleScript Support #867

Uh oh!

Conversation

SKaplanOfficial commented Apr 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cyanzhong commented Apr 6, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SKaplanOfficial Apr 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cyanzhong commented Apr 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SKaplanOfficial commented Apr 6, 2025

Uh oh!

cyanzhong commented Apr 6, 2025

Uh oh!

cyanzhong commented Apr 6, 2025

Uh oh!

SKaplanOfficial commented Apr 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cyanzhong commented Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SKaplanOfficial commented Apr 7, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SKaplanOfficial commented Apr 5, 2025 •

edited

Loading

SKaplanOfficial Apr 6, 2025 •

edited

Loading

cyanzhong commented Apr 6, 2025 •

edited

Loading

SKaplanOfficial commented Apr 6, 2025 •

edited

Loading

cyanzhong commented Apr 7, 2025 •

edited

Loading