One trick to finding JXA documentation is simply to look at the AppleScript documentation and translate the code to JavaScript syntax, or, depending on what you've doing, look at the Objective-C Cocoa documentation and translate the syntax.
For example, to obtain the current date and one day from now, in Objective-C you might write:
AppleScript looks fantastically simple and easy to pick up until you actually come to write some. Then, because of the "conversational" structure of it, it feels more like guessing the right magic incantation than programming.
It certainly reads nicer to non-programmers, but I feel like writing it requires just as much learning as any more "traditional" scripting language, so I'm not really sure what the benefit is.
Funny enough, back when the Mac Automation devs were still getting JXA ready to throw away, one of the things I told Sal Soghoian to do was to add automatic AS-to-JS syntax translation to Script Editor’s Log pane. While it only translates outgoing Apple events, not native AS code, 99% of the time JS users already know how to write general JS code, and it’s the application-specific references and commands they’re struggling to form.
Back when appscript was still a thing I hacked together a quick-n-dirty AppleScript-command-to-Python/Ruby/ObjC translator app which appscript users absolutely adored, plus it greatly reduced the number of “How do I…” support questions because, more often than not, users already had a working example in AppleScript which they could just run through the translator to get the answer for themselves.
Needless to say, Sal Soghoian completely ignored my expert recommendation for this killer feature which could be implemented in a day, choosing instead to dump JXA and its few hapless users down the same black hole of nothingness as all his other product failures. PEBKAC. Not Invented Here. So it goes.
--
[edited to add]
Just d/led the JavaScriptOSA zip from the appscript project page on SourceForge, and the bundled JABDemo.app still works. It’s not codesigned so you’ll have to right-click the app to Open it, overriding the security warnings, but it still works even on 10.15 (caveat any bugs in the underlying JavaScript Apple event bridge, of which there were a few, plus the endless string of permission requests whenever you try to control another app). Example:
Original AppleScript commands:
tell app "textedit" to get name of document 1
tell app "finder" to count every folder of home whose name begins with "D"
I'm already using MenuHammer[1] (menu system inspired by Spacemacs) and Spectacle.
But plan for a next year or two is to build custom ergo keyboard (r/ErgoMechKeyboards has a bunch of interesting stuff - I'm aiming for Corne or Iris) and then to customize keyboard layout + Hammerspoon to reduce mouse usage as much as possible. With various VIM plugins available for editors and Firefox (Tridactyl) I'm quite optimistic.
Exactly. It's been years since first released and nothing is really out there to tell you how to use it. I wish they would finish it up as it is much better that AppleScript.
That will never happen. JXA is junk, same as Scripting Bridge before it; and they never shit to fix SB even when they had years to do it. There’s a reason Apple finally disbanded the Mac Automation team and fired the PM responsible. JXA should’ve saved Mac Automation, but it killed it instead.
Worst part is: it should never have come to this.
(For those that don’t know, I am the world expert at building production-ready Apple event bridges, with half-a-dozen under my belt. Outside of myself, Dave Winer’s Userland, and the original AppleScript creators, no-one else on the planet has ever managed this.)
Immediately after JXA was surprised-announced at WWDC14, I dropped everything else, reached out to Sal Soghoian (Mac Automation PM), and crash-coursed six weeks of testing and critiquing JXA, up to and including writing a nearly-complete “JavaScriptOSA” reference implementation for the JXA devs to learn from, or just outright steal.
Even rushed and unfinished, JavaScriptOSA showed what JXA should’ve been. And they had double the developers, all the AppleScript source and internal Apple documentation, and a year. You can d/l it here:
While the Xcode project is far too old to build now and some of that code is a lashup of which I’m not proud, the prebuilt component may still work in Script Editor (though I’ve not tested it in years), as should the standalone “demo” app I bundled with it.
Bear in mind, my JavaScriptOSA implementation[1] was based on my previous appscript work [2], which had alrady proven itself a genuine AppleScript replacement years earlier. Apple even considered including Python and Ruby appscript in Mac OS X Leopard, so it’s not like my code wasn’t already known about, read, or used by folks within Apple. But the Mac Automation team still thought they knew better than a production-proven solution that had at its height a couple thousand extremely happy users, whereas their own previous attempt had only proven an embarrassing failure.
I didn’t get so much as a thanks-but-no-thanks; 200+ work hours straight down the crapper. And JXA shipped half-baked and broken, and immediately abandoned to sink without trace. I scrapped my plan to write the book on Automating your Mac with JavaScript, because you can’t write really good books about really lame broken technology, at least not without losing your mind. (I should know: I lead-authored one of the last AppleScript books.) Apple’s last, best chance to turn Mac Automation around, pissed up the wall and forgotten just as fast.
Honestly, Apple’s real mistake was not firing that preening incompetent, Sal Soghoian, years sooner, while there was still something worth saving.
..
Okay, so with hindsight, JXA was never likely to succeed, even if they had done its implementation and marketing right. As an OSA language component, it lives in its own little closed world, completely separate to Node.js and its vast npm ecosystem. Even in 2014 Node was already killing it in the JS-on-server-and-desktop wars, but instead of “Embrace and Extend” JXA chose “Not Invented Here” instead.
Worse, JXA is built on OSA which is a ComponentManager technology; a hideously ancient, inherently insecure, and long-deprecated in-process plugin architecture. Thus the JXA implementation was already obsolete even before it shipped. A straight port of node and npm CLI tools onto JavaScriptCore with a V8 API compatibility layer for C-based extensions would have been the right choice. But the Mac Automation team didn’t see, because like their technologies they exist in a closed little world completely isolated from everything and everyone else.
One More Thing: Around the same time as Sal was getting his ass ejected from Apple, I wrote one more Apple event bridge, nodeautomation, just to prove my point that creating a competent AppleScript alternative for a massively popular, developer-friendly language is both quickly and easily achievable, so Sal’s team had absolutely no excuse for fucking it up twice.[3] Although it looks like recent macOS/Node updates have broken the build (again), so you’d need to run it on an older platform if you wanted to play with it.
I can still vouch for Python3-appscript, as that’s what I use myself, but I no longer provide support for any of them because as much as I love Apple event automation and the incredible solutions it makes easy to build, even I accept it has been utterly buggered to death now, and the only question remaining is how much longer till Apple finally put it out our misery for good.
..
That said, if any Hammerspoon fans wish to cross my palm with silver, I’ve previously offered to do a Lua-Apple event bridge for it, and would be happy to do so even now. (Misery loves company.:)
--
[1] No relation to Late Night Software’s original JavaScriptOSA, which like JXA was also riddled with flaws and never went anywhere.
[3] Or thrice, if you count the time after the JXA fiasco that I offered to give Sal my SwiftAutomation bridge [4] outright, just as Swift was starting its meteoric rise, and he threw it back in my face. I’ve dealt with some stupid PMs over the years, but Jebus that one was dumber’n all those other stumps put together. What a waste.
One trick to finding JXA documentation is simply to look at the AppleScript documentation and translate the code to JavaScript syntax, or, depending on what you've doing, look at the Objective-C Cocoa documentation and translate the syntax.
For example, to obtain the current date and one day from now, in Objective-C you might write:
The equivalent in JavaScript is simply
> look at the AppleScript documentation and translate the code to JavaScript syntax
Yeah, I can’t do this. It’s non-obvious to me how it translates until I actually stumble upon the correct thing.
AppleScript looks fantastically simple and easy to pick up until you actually come to write some. Then, because of the "conversational" structure of it, it feels more like guessing the right magic incantation than programming.
It certainly reads nicer to non-programmers, but I feel like writing it requires just as much learning as any more "traditional" scripting language, so I'm not really sure what the benefit is.
4 replies →
Funny enough, back when the Mac Automation devs were still getting JXA ready to throw away, one of the things I told Sal Soghoian to do was to add automatic AS-to-JS syntax translation to Script Editor’s Log pane. While it only translates outgoing Apple events, not native AS code, 99% of the time JS users already know how to write general JS code, and it’s the application-specific references and commands they’re struggling to form.
Back when appscript was still a thing I hacked together a quick-n-dirty AppleScript-command-to-Python/Ruby/ObjC translator app which appscript users absolutely adored, plus it greatly reduced the number of “How do I…” support questions because, more often than not, users already had a working example in AppleScript which they could just run through the translator to get the answer for themselves.
Needless to say, Sal Soghoian completely ignored my expert recommendation for this killer feature which could be implemented in a day, choosing instead to dump JXA and its few hapless users down the same black hole of nothingness as all his other product failures. PEBKAC. Not Invented Here. So it goes.
--
[edited to add]
Just d/led the JavaScriptOSA zip from the appscript project page on SourceForge, and the bundled JABDemo.app still works. It’s not codesigned so you’ll have to right-click the app to Open it, overriding the security warnings, but it still works even on 10.15 (caveat any bugs in the underlying JavaScript Apple event bridge, of which there were a few, plus the endless string of permission requests whenever you try to control another app). Example:
Original AppleScript commands:
Generated JavaScript equivalents:
I mean, I wrote the thing and even to me years later it’s still like freaking voodoo! :)
You can use TypeScript to improve the tooling: https://github.com/JXA-userland/JXA
1 reply →
That's a strategy to guess code but it doesn't yield documentation.
And there's Fennel - an Lisp that compiles to Lua which makes writing Spoons (Hammerspoon plugins) pure joy.
https://fennel-lang.org/
If you like Fennel, you're gonna like Spacehammer - Spacemacs inspired Hammerspoon config written in Fennel. https://github.com/agzam/spacehammer
Thanks, I'll take a look.
I'm already using MenuHammer[1] (menu system inspired by Spacemacs) and Spectacle.
But plan for a next year or two is to build custom ergo keyboard (r/ErgoMechKeyboards has a bunch of interesting stuff - I'm aiming for Corne or Iris) and then to customize keyboard layout + Hammerspoon to reduce mouse usage as much as possible. With various VIM plugins available for editors and Firefox (Tridactyl) I'm quite optimistic.
[1] https://github.com/FryJay/MenuHammer
"...impossible to find documentation for"
Exactly. It's been years since first released and nothing is really out there to tell you how to use it. I wish they would finish it up as it is much better that AppleScript.
That will never happen. JXA is junk, same as Scripting Bridge before it; and they never shit to fix SB even when they had years to do it. There’s a reason Apple finally disbanded the Mac Automation team and fired the PM responsible. JXA should’ve saved Mac Automation, but it killed it instead.
Worst part is: it should never have come to this.
(For those that don’t know, I am the world expert at building production-ready Apple event bridges, with half-a-dozen under my belt. Outside of myself, Dave Winer’s Userland, and the original AppleScript creators, no-one else on the planet has ever managed this.)
Immediately after JXA was surprised-announced at WWDC14, I dropped everything else, reached out to Sal Soghoian (Mac Automation PM), and crash-coursed six weeks of testing and critiquing JXA, up to and including writing a nearly-complete “JavaScriptOSA” reference implementation for the JXA devs to learn from, or just outright steal.
Even rushed and unfinished, JavaScriptOSA showed what JXA should’ve been. And they had double the developers, all the AppleScript source and internal Apple documentation, and a year. You can d/l it here:
https://sourceforge.net/projects/appscript/files/JavaScriptO...
While the Xcode project is far too old to build now and some of that code is a lashup of which I’m not proud, the prebuilt component may still work in Script Editor (though I’ve not tested it in years), as should the standalone “demo” app I bundled with it.
Bear in mind, my JavaScriptOSA implementation[1] was based on my previous appscript work [2], which had alrady proven itself a genuine AppleScript replacement years earlier. Apple even considered including Python and Ruby appscript in Mac OS X Leopard, so it’s not like my code wasn’t already known about, read, or used by folks within Apple. But the Mac Automation team still thought they knew better than a production-proven solution that had at its height a couple thousand extremely happy users, whereas their own previous attempt had only proven an embarrassing failure.
I didn’t get so much as a thanks-but-no-thanks; 200+ work hours straight down the crapper. And JXA shipped half-baked and broken, and immediately abandoned to sink without trace. I scrapped my plan to write the book on Automating your Mac with JavaScript, because you can’t write really good books about really lame broken technology, at least not without losing your mind. (I should know: I lead-authored one of the last AppleScript books.) Apple’s last, best chance to turn Mac Automation around, pissed up the wall and forgotten just as fast.
Honestly, Apple’s real mistake was not firing that preening incompetent, Sal Soghoian, years sooner, while there was still something worth saving.
..
Okay, so with hindsight, JXA was never likely to succeed, even if they had done its implementation and marketing right. As an OSA language component, it lives in its own little closed world, completely separate to Node.js and its vast npm ecosystem. Even in 2014 Node was already killing it in the JS-on-server-and-desktop wars, but instead of “Embrace and Extend” JXA chose “Not Invented Here” instead.
Worse, JXA is built on OSA which is a ComponentManager technology; a hideously ancient, inherently insecure, and long-deprecated in-process plugin architecture. Thus the JXA implementation was already obsolete even before it shipped. A straight port of node and npm CLI tools onto JavaScriptCore with a V8 API compatibility layer for C-based extensions would have been the right choice. But the Mac Automation team didn’t see, because like their technologies they exist in a closed little world completely isolated from everything and everyone else.
One More Thing: Around the same time as Sal was getting his ass ejected from Apple, I wrote one more Apple event bridge, nodeautomation, just to prove my point that creating a competent AppleScript alternative for a massively popular, developer-friendly language is both quickly and easily achievable, so Sal’s team had absolutely no excuse for fucking it up twice.[3] Although it looks like recent macOS/Node updates have broken the build (again), so you’d need to run it on an older platform if you wanted to play with it.
I can still vouch for Python3-appscript, as that’s what I use myself, but I no longer provide support for any of them because as much as I love Apple event automation and the incredible solutions it makes easy to build, even I accept it has been utterly buggered to death now, and the only question remaining is how much longer till Apple finally put it out our misery for good.
..
That said, if any Hammerspoon fans wish to cross my palm with silver, I’ve previously offered to do a Lua-Apple event bridge for it, and would be happy to do so even now. (Misery loves company.:)
--
[1] No relation to Late Night Software’s original JavaScriptOSA, which like JXA was also riddled with flaws and never went anywhere.
[2] http://appscript.sourceforge.net/
[3] Or thrice, if you count the time after the JXA fiasco that I offered to give Sal my SwiftAutomation bridge [4] outright, just as Swift was starting its meteoric rise, and he threw it back in my face. I’ve dealt with some stupid PMs over the years, but Jebus that one was dumber’n all those other stumps put together. What a waste.
[4] https://hhas.bitbucket.io/
How did you get into this?
1 reply →