6 April 2011Searching Websites from the Terminal

A few weeks ago Peter Hosey wrote Apple documentation search that works. Peter documents how to quickly search the Apple Developer Connection from within Chrome and OmniWeb. I use Safari – d’oh! However, I already have a workflow for searching various websites and it was easy to add ADC search. This post describes how I to replicate my workflow.

My approach is to run shell scripts from the terminal which construct a URL and open it with the default browser.

Aside: I came up with this approach last summer while playing around with URIs in a desktop context. URIs are a really powerful concept. I wanted to created a system that let users define their own URI schemes and a mechanism to autocomplete/suggest URIs. You can view Spotlight to be an instance of this that works exclusively with the file: scheme. For example, wikipedia:Eggs Benedict, cal:01/23/45. I got as far as creating an app that could register arbitrary schemes with the OS and rewrite them with a regex.

Before I continue I must make a confession – my Bash skills are mediocre at best. I’ve read The UNIX Programming Environment and there’s a Linux quick reference guide sitting on my desk.

Step one: getting to the terminal really quickly

For this workflow to be useful the terminal needs to be instantly accessible. There are a few apps that integrate the terminal into the GUI; DTerm and Visor. These are a bit to fussy for my taste, and Terminal.app works fine for me so why reinvent the wheel? The solution I have is to add a global keyboard shortcut that launches Terminal.app. There are few apps that can create global hot keys; FastScripts and QuicKeys. I picked Spark because it doesn’t add UI cruft (I hate unnecessary cruft being added to my menu bar) and also it’s free!

Here’s a screen shot of the Spark settings:

I have a British keyboard so the § key is directly above tab (it’s in the place of ` on a US keyboard). Finding a global hot key that doesn’t interfere with other apps is tricky, but here are some suggestions:

• cmd + alt + tab
• cmd + esc (this is actually associated with Front Row. To de-associate it  from Front Row go to System Preferences -> Keyboard -> Keyboard Shortcuts -> Front Row)
• cmd + § (British layout. I used to use this to move focus to the menu bar – but I now use cmd + ? a.k.a. cmd + shift + /)
• cmd + alt + § (British layout)

Step two: Creating a folder to store Shell Scripts

I keep my scripts in ~/Library/ShellScripts (~ is shorthand for the current users home folder, e.g. /Users/Ben). This fits in nicely with the OS X file system conventions and is easy to get to.

Step three: Giving Bash access to the Shell Scripts folder

When a user enters a filename the file is looked for in the current working folder and the folders listed in the PATH environment variable. We need to add the folder from step 2 to PATH. There are various config files which can be used to set environment variables. I use ~/.profile. Be aware that files with a ‘.' prefix are hidden in Finder.

1. Create ~/.profile with the following terminal command:
   touch ~/.profile (if it already exists then the content is not changed but the accessed and modified dates are set to now).
2. Open ~/.profile with the following terminal command:
   open ~/.profile (this should open in the default text editor, which is probably TextEdit).
3. Append the following line:
   PATH=$PATH;{SCRIPTS_FOLDER}
   e.g. PATH=$PATH;/Users/Ben/Library/ShellScripts

Step four: Creating the Shell Scripts

Shell scripts are simply text files with their executable bit turned on. I prefer to give the files relatively verbose names and create a shortcut (a.k.a. symlink) to them. You could just name the script the final name and ditch the symlink. The follow steps create a script for searching the iOS section of Apple Developer Connection:

1. Open a text editor and save the following to {SCRIPTS_FOLDER}/adcref-ios.sh
#! /bin/bash
open "http://developer.apple.com/library/ios/search/?q=$*"
2. In terminal change to the scripts folder, e.g.:
   cd ~/Library/ShellScripts
3. Make the script executable:
   chmod +x adcref-ios.sh
4. Create a symlink with a uber short name:
   ln -s ~/Library/ShellScripts/adc-ios.sh diNote that we are specifying the destination script relative to the users home folder. Also, before creating the symlink check that the name is not used by another file.
5. Done! You can now search the iOS documentation from the terminal like so:
   di CATiledLayer example

Other search scripts

• Mac section of Apple Developer Connection:
  #! /bin/bash
open "http://developer.apple.com/library/mac/search/?q=$*"
• Wikipedia:
  #! /bin/bash
open "http://en.wikipedia.org/wiki/$*"
• Google:
  #! /bin/bash
open "http://google.com/search?q=$*"
• Stack Overflow:
  #! /bin/bash 
open "http://stackoverflow.com/search?q=$*"