Scripting the Leopard Terminal

Hypothetical situation: you’re sitting down with your favorite tasty beverage close at hand for some Rails hacking, and what commands do you run every single time? It’s probably something like this:

RSI
cd Projects/KillerApp

mate .

rake log:clear

tail -f log/development.log


[Command – T for new tab]

cd Projects/KillerApp

mongrel_rails start


[Command – T for new tab]

cd Projects/KillerApp

ruby script/console


[Command – T for new tab]

cd Projects/KillerApp

rake


…etc…

Hmmm. We’re coding DRY, but this bootstrap process doesn’t seem very DRY. This had been bugging me, so I set out on a Google quest to learn to script Terminal.app in Leopard so that I could do something about it. I first looked at AppleScript, since that’s the de facto scripting language of all things Apple. Given a specimen, I could decipher what it was trying to do reasonably well, but going the other way was difficult — starting with a goal, I was generally unsuccessful in trying to express it in AppleScript. This was the best I could come up with:

utopia
tell executive SteveJobs
   tell developers at Apple
      set theScriptingLanguage of OSX to Ruby
   end tell
end tell

Which was a good thought, but didn’t actually do much. At RubyConf last year, Laurent Sansonetti talked about RubyOSA, a scripting bridge between Ruby and the Apple Event Manager, which sounds great, because you can code in Ruby and control AppleScript-able applications, like iTunes. So I ran this:

fail
require 'rbosa'
terminal = OSA.app('Terminal')

Which resulted in this rather discouraging output:

rubyosa-error
RuntimeError: Can't get the target bundle signature
  from /Library/Ruby/Gems/1.8/gems/rubyosa-0.4.0/lib/rbosa.rb:329:in `__scripting_info__'
  from /Library/Ruby/Gems/1.8/gems/rubyosa-0.4.0/lib/rbosa.rb:329:in `app'
  from (irb):3

Hmmm. Not exactly useful. Maybe if I did my coding in iTunes, I could use RubyOSA to build some useful automation. Hopefully someone at Apple can fix Terminal — Hint, Hint. Back to Google…

I eventually ran across Matt Mower’s scripting a better ‘cd’ and then some article. Beautiful. Exactly what I wanted. Except I didn’t want to have to switch to iTerm just to use it. I’m fairly happy with the native Terminal.app in Leopard — the tabs are nice. My biggest complaint is that you cannot name individual tabs, which seems like a glaring omission. Hopefully that will be updated soon.

So Matt’s gp command uses another Ruby / Apple event bridge, called Appscript, which “allows you to control scriptable Mac OS X applications using ordinary Ruby scripts”. Sounds cool, and most of the examples feature TextEdit, which isn’t Terminal, but at least is more of a developer application than iTunes, so we seem to be on the right track.

gem install rb-appscript, and let’s play. In IRB:

appscript1
>> require 'appscript'
>> include Appscript
>> term = app('Terminal')
=> app("/Applications/Utilities/Terminal.app")
>> term.windows
=> app("/Applications/Utilities/Terminal.app").windows
>> term.windows.first
=> app("/Applications/Utilities/Terminal.app").windows.first

Okay, this is a bit strange — it seems to just repeat what you say back to you. After a bit of playing, I understand what’s going on. Some of the methods aren’t executed until you explicitly tell them to execute. For instance:

appscript2
>> term.windows.get
=> [app("/Applications/Utilities/Terminal.app").windows.ID(915), app("/Applications/Utilities/Terminal.app").windows.ID(498), app("/Applications/Utilities/Terminal.app").windows.ID(667)]
>> term.windows.first.get
=> app("/Applications/Utilities/Terminal.app").windows.ID(915)

Why? Most likely, this is for efficiency reasons. With many of these “Event Bridge” solutions, there is a significant “toll” that must be paid to cross the bridge. If we can batch together a string of method invocations and send them across the bridge for a single round trip, it performs much better than multiple round trips would.

At any rate, we can now get a handle on the Terminal application and its already-open windows. The next step is to be able to open new windows and tabs. There is a somewhat useful tool on the rb-appscript download page called ASDictionary, which can examine an application and dump out the objects and methods that it exposes to the bridge. Kinda like rdoc for AppleScript. Running the dictionary against Terminal.app, I found the do_script(command) method, which, when called on the terminal application object, launches a new terminal window and runs the specified UNIX command in it.

appscript3
>> term.do_script("ls")
=> app("/Applications/Utilities/Terminal.app").windows.ID(951).tabs[1]

If you’re following along, you should have a new Terminal window containing a listing of the files and folders in your home directory. Also, notice that the command returns a reference to the first (and only) tab in the new window — we’ll come back to that later. So, new windows, check; now for new tabs.

The Appscript examples show creating new TextEdit documents by executing:

appscript4
app('TextEdit').documents.end.make(:new => :document)

And the Appscript dictionary of Terminal showed the make method, and window and tab classes, so I figured something like this might work:

appscript5
>> window = term.windows.first.get
=> app("/Applications/Utilities/Terminal.app").windows.ID(915)
>> window.make(:new => :tab)
Appscript::CommandError: CommandError
    OSERROR: -10000
    MESSAGE: Apple event handler failed.
    COMMAND: app("/Applications/Utilities/Terminal.app").windows.ID(915).make({:new=>:tab>> window = term.windows.first.get

=> app("/Applications/Utilities/Terminal.app").windows.ID

>> window.make(:new => :tab)

Appscript::CommandError: CommandError

    OSERROR: -10000

    MESSAGE: Apple event handler failed.

    COMMAND: app("/Applications/Utilities/Terminal.app").windows.ID.make({:new=>:tab})

from /Library/Ruby/Gems/1.8/gems/rb-appscript-0.4.0/lib/appscript.rb:505:in `_send_command’
from /Library/Ruby/Gems/1.8/gems/rb-appscript-0.4.0/lib/appscript.rb:585:in `method_missing’
from (irb):11

Appscript is having none of that. After many frustrating, fruitless attempts to create a new tab, I found a workaround in native AppleScript here. Here’s the Appscript translation:

appscript6
app("System Events").application_processes[
        "Terminal.app"
     ].keystroke("t", :using => :command_down)

Well, okay, sending a Command-T keystroke works, but it’s a little disappointing. Anyone who knows how to programatically create a new tab, feel free to chime in on the comments, and I’ll update the script.

do_script(command) also takes an optional parameter specifying options. One of the available options is :in, which tells terminal in which window and tab to run the command. Putting this together, we can run a command in the new tab we just created:

appscript7
app('Terminal').do_script("ls", :in => window.tabs.last.get)

We don’t have a handle to the new tab, because it was created via hackery, so we need a handle to its parent window object so we can get at its tabs. Well, our first command we ran with do_script returned us a handle to the first tab of the window, surely we can get the window from that. Right? Anyone?

appscript8
>> tab = term.do_script("ls")
=> app("/Applications/Utilities/Terminal.app").windows.ID(1159).tabs[1]
>> tab.window
RuntimeError: Unknown property, element or command: 'window'
  from /Library/Ruby/Gems/1.8/gems/rb-appscript-0.4.0/lib/appscript.rb:591:in `method_missing'
  from (irb):11
  from :0

(Sigh) Not so much. Time for a hack on a hack, and this one is just embarrassing. Observant readers have probably noticed that the tab referenced shows its parent window id in the string of object references. What if we use that to get a handle to the parent window? Something like this:

evil-hack
>> window = eval("app(\"/Applications/Utilities/Terminal.app\").windows.ID(1159)")
=> app("/Applications/Utilities/Terminal.app").windows.ID(1159)

I’m not proud of it, but it works. Again, if someone knows the “right” way to do this, please let me know—although programatically creating a tab should obviate the need for this hack, too.

Another thing I wanted to change from the original script was that with Matt’s solution, you need to specify the type of project you are opening, either as a command-line argument, or by symlinking the script to a new name with the type embedded. I want the computer to figure all that out for me. Computers are real smart. So my script includes some configurable heuristics for determining project type based on the folder contents. You should be able to specify set of files and folders that defines a project type. For Rails, I used the “skeleton” folders that every Rails app starts with. I haven’t been programming in Erlang very long, so honestly I just guessed at the folders based on some projects I have seen. If you’re a more experienced Erlang programmer, and feel that the project detection or task list should be changed, please let me know.

Matt later enhanced his script to label the iTerm tabs so that you can easily find the tab you need, so naturally I stole incorporated this idea too. It sorta works in Leopard’s Terminal—it does change the name of the Terminal window, but the tab name is unaffected, so you still have to flip through the tabs and watch the window name. This is my biggest request for a feature enhancement for the Terminal, Hint, Hint again, Apple.

So enjoy. You can use the script anywhere — it will look first in your current directory for a matching folder (you only have to specify a non-ambiguous substring of the project folder name), then falls back to the “project root” folder you specify (currently ~/development, ‘cause that’s what I use.). You can configure how deep it should recurse your projects so that the disk seeking time doesn’t eat up all the time you’re saving from not typing the same “cd” commands over and over.

You can download the finished script here. I call it hack, because hack KillerApp flows so nicely as a command. Also, that’s the way I roll. Feel free to send in money, or flattery, or hate mail, I suppose. Thanks to Matt Mower for the inspiration and also to all the other references I’ve linked!

Posted by Solomon White Wed, 28 Nov 2007 19:38:00 GMT

Read full article 16 comments


Comments

  1. has about 4 hours later:
    Okay, this is a bit strange—it seems to just repeat what you say back to you. After a bit of playing, I understand what’s going on. Some of the methods aren’t executed until you explicitly tell them to execute.

    Technically, what happens is that all ‘property’ and ‘element’ methods return an Appscript::Reference instance; only ‘command’ methods actually send an Apple event to the target application.

    Apple event IPC is quite unusual in that it’s actually based on remote procedure calls plus queries, rather than the more common object-oriented approaches used by COM, CORBA, Distributed Objects, etc. As you say, this is for sake of efficiency: Mac OS 7-9 had pretty awful multiprocessing support, and context switches were very expensive and limited to a maximum of 60 per second. The query-based “do more with less” approach minimises the number of Apple events that need to be sent to get things done. Takes a bit of getting used to if you’re coming from an OOP background, and isn’t without its problems (it’s notoriously tricky to implement reliably on the application side), but when it does work it’s really quite elegant.

    Anyone who knows how to programatically create a new tab, feel free to chime in on the comments, and I’ll update the script.

    Looks like Terminal’s ‘make’ command is broken, unfortunately; normally I’d expect at least one of the following to work (depending on how the application likes the insertion location constructed):

    
app('Terminal').make(:new=>:tab, :at=>app.windows[1])
app('Terminal').make(:new=>:tab, :at=>app.windows[1].tabs.end)

    but neither of these worked, nor did any other variations I tried. I also tried making new windows, but that returned errors too:

    
app('Terminal').make(:new=>:window)
app('Terminal').make(:new=>:window, :at=>app.windows.end)

    It’s frustrating, but as longtime AppleScripters can tell you, these sorts of obvious bugs are unfortunately not that uncommon, even in Apple applications. All I can suggest is filing a bug report with Apple and keep using your System Events-based workaround to script Terminal’s GUI in the meantime.

    Well, our first command we ran with do_script returned us a handle to the first tab of the window, surely we can get the window from that. Right? … Not so much. Time for a hack on a hack, and this one is just embarrassing. … Again, if someone knows the “right” way to do this, please let me know

    If you dig down through appscript’s API layers you do eventually come to a visitor-style API that allows you to get at the innards of application references. However, it’s not publicly documented (info is available on request though) and not something I’d encourage- as you say, it’s really the application’s job to provide users with the info they need, and anything else is just a hack.

    Since Cmd-T always creates the new tab in the frontmost window, personally I’d just wing it and use:

    
window_ref = app('Terminal').windows[1].get

    By-index references aren’t as reliable as by-id reference since they tend to change according to stacking order, but if you send the above immediately after the tab is created (i.e. before anyone has a chance to bring another Terminal window frontmost) you should get a permanent by-id reference to the correct window back from Terminal:

    
app("/Applications/Utilities/Terminal.app").windows.ID(1159)

    Unfortunately, while windows can be identified by unique id, it looks like tabs are still stuck with the by-index form, so if someone or something else creates a new tab in the same window later on I’m not quite sure how you’re meant to keep a reliable handle on your own tab. Though again this is a not uncommon dilemma when scripting applications, and I expect most folks just wing it here too, but feel free to file a feature request with Apple asking for Terminal tabs to support the by-id reference form in future releases.

    HTH

    has
    —
    http://appscript.sourceforge.net
    http://rb-appscript.rubyforge.org

  2. Solomon White about 12 hours later:

    @has:

    Wow, excellent info — thanks for the response. Straight from the source!

    Regarding timing / stacking issues, I’ve run into this with hack. Sometimes, after I set the terminal window foremost, and before system events can send the keystroke, TextMate will pop up and eat the Command – T. (so I get the ever-so-useful “jump to file” dialog, and no new tab) This was a bit surprising, since I’m asking system events to send the keystroke specifically to the Terminal application.

    If anyone runs into this, you might have to fiddle with the order of your tasks — commands that launch new windows might be best served last.

    Thanks again!

  3. has about 16 hours later:

    Sometimes, after I set the terminal window foremost, and before system events can send the keystroke, TextMate will pop up and eat the Command – T.

    Use app('Terminal').activate to ensure the Terminal application is frontmost before sending the keystroke. While some GUI Scripting commands allow you to specify a target process, I think keystrokes automatically go to the frontmost application.

    HTH

  4. Matt Mower about 17 hours later:

    Hi Solomon.

    Thanks for the link back. I’m glad you took on the challenge of Terminal.app, I had a go but didn’t have your grit. I made a few further comments:

    http://matt.blogs.it/entries/00002722.html

    Cheers,

    Matt.

  5. Solomon White about 21 hours later:

    Thanks for commenting on my script. (I tried to post this comment on your blog, but I get a 403). find is working for me so far — it was quite slow until I started prune-ing result branches and limiting recursion depth. I’ve seen that you have mentioned releasing gp as a gem. Maybe we should combine our efforts?

    Thanks,

    Solomon

  6. Matt Schick 11 days later:

    Thanks for the new tab work around via SystemEvents. I was trying to do the same thing for safari and it wasn’t having any of that ‘.make(:new => :tab …’ either.

  7. jeff about 1 month later:

    Nice work Solomon! I’ve been looking for something like this. I took your examples and packaged it up as a little utility:

    https://wush.net/svn/public/terminit/

  8. nb 3 months later:

    Cool stuff, Solomon. Based on your work, I created a similar script that suits my work flow. Check it out:

    http://the-banana-peel.saltybanana.com/2008/02/new-terminal-tab-in-current-directory.html

  9. nb 3 months later:

    Cool stuff, Solomon. Based on your work, I created a similar script that suits my work flow. Check it out:

    http://the-banana-peel.saltybanana.com/2008/02/new-terminal-tab-in-current-directory.html

  10. nuzz 4 months later:

    is there a way to add modifiers to the keystroke? ex. command + shift + t I can’t seem to figure out this can be done. I started using this SIMBL based terminal.app plugin that allows you to rename the tabs properly.

    http://ericanderson.us/2008/03/02/terminalapp-tab-namer-v01-alpha/

    Great writeup, this has helped me a lot.

  11. nuzz 4 months later:

    well I think I answered my own question.

    app(“System Events”).application_processes[“Terminal.app”].keystroke(“t”, :using => [:command_down, :shift_down])

    Now all I need to figure out is how to programatically supply text to the tab naming plugin that the cmd+shift+t keystroke initiates.

  12. Chris Blackburn 5 months later:

    Thanks Solomon! I took what you discovered and made my own script to set different colors for each type of tab in my workflow.

    It is here for anyone interested

    Thanks again and keep posting!

  13. Tony 6 months later:

    Thank You!

  14. Tony 6 months later:

    Thank You!

  15. Matthew Hutchinson over 1 year later:

    I took this as inspiration for writing a little project launcher script; Its on git hub right now, read the README for more info on setting up and using.

    ABOUT

    A simple, small Ruby script to launch commands on the standard multi-tabbed OSX Terminal (using Appscript). Project configuration is set in launcher_config.yml, where detection (based on a directory name, what folders it contains) and terminal commands can be setup. The example configuration shows a Rails and Erlang project type.

    ,Matt

  16. Adam Walters over 1 year later:

    Beaaaaaautiful, just what i was looking for, rb-appscript and all. Thanks!