MacResearch

Author: Geoff Hutchison
Website: http://geoffhutchison.net/

In previous tutorials for presenting Mac interfaces for command-line tools, I looked at Platypus and CocoaDialog. Last time I showed how you could add some user interaction to our command-line tools. Generally that was limited to simple dialog boxes or showing progress and output from the command-line.

This time around, I'm going to highlight Pashua, a freeware tool which allows you to have richer Mac windows for setting options, popup menus, finding files, checkboxes, and more.

Alone or Together

Pashua includes comprehensive documentation, examples, and a double-clickable application shell. That means that you can either use Pashua by itself (by replacing the script and configuration in the example) or in concert with Platypus, much like I described for CocoaDialog previously. For this tutorial, I'll give examples from the Pashua examples, rather than combining Platypus and Pashua.

It's worth pointing out that none of the tools I've described "replaces" another. Each has advantages. For example, if you wish to show a "percent complete" dialog, you'll need to use CocoaDialog. Platypus is also the easiest way to show the text output from a command-line tool.

One downside of Pashua is that the documentation or examples isn't online. So if you want to learn more, you should download it yourself. There's also a great one-page tutorial at MacDevCenter. (Keep in mind that the MacDevCenter tutorial is for an older version of Pashua and uses different syntax.)

Building a Window

They say a picture is worth a thousand words:

Pretty cool, hmm?

In general, Pashua can be used from a huge range of scripting languages and the shell. Again, I'm going to use Perl for my examples, but as you'll see it doesn't matter much as the main portion of Pashua is the configuration file (or configuration string) which builds up the window to display. This is set by Pashua itself, not Perl or Python or Ruby or whatever language you want to use for your command-line tool.

The configuration is a little reminiscent of HTML -- you use text and attributes to define what you want in the box, and everything will be arranged for you. This means that you don't get pixel-perfect arrangement of items, but don't have to worry about pixel locations either.

Start It Up

I'm going to edit the "Doubleclickable Example.app" which comes with Pashua and add our tutorial script. You need to go into the Application Package:

Once there, you'll need to go into the Contents folder, then the MacOS folder:

This particular example uses Perl, so there's a Pashua.pm library, which defines the Perl interface to Pashua. We want to edit the "Doubleclickable Example" in a text editor -- it's just a Perl script. Before I forget -- the naming rule here is simple. If I have "Doubleclickable Example.app" as my main app bundle, then the script run by Pashua is "Doubleclickable Example." If you had "Foo.app", it would look for an executable script named "Foo."

I'm going to ignore the example code currently in that file and show you what I did to create the example window above.

Configure

# Define what the dialog should be like
# Take a look at Pashua's Readme file for more info on the syntax
my $conf = <

I've tried to give a few examples here of the different elements Pashua can include in a window. In each case, you create an element by defining a new variable and setting its type:
tf.type = textfield # a standard non-password text field

In most cases, you can set the label and tooltip and width as well:
pop.label = Example popup menu
pop.width = 310
pop.tooltip = Favorite MacResearch.org Contributor

The configuration can either be passed as a string to Pashua or as a text file. This means you can save your configuration for others to translate into other languages or alter as needed. Or you can generate the string on-the-fly based on results from your script.
You can also easily set multiple elements of each type. For example, two sets of radio buttons might look like this:
# First set of radio buttons
rb1.type = radiobutton
rb1.label = Example radiobuttons
rb1.option = Larry
rb1.option = Curly
rb1.option = Moe

# Another set (note we use a different name)
# Remember that the rb2 name can be whatever we want. "foo2" would work as a key too.
rb2.type = radiobutton
rb2.label = More buttons!
rb2.option = Steve Jobs
rb2.option = Bill Gates
rb2.option = Linus Torvalds
And Away We Go!
Once you've set the configuration, you just call Pashua and get back a hash (or dictionary) of the values chosen by the user. This makes it extremely easy to pass options on to your command-line tools.
# Pass the configuration string to the Pashua module
my %result = Pashua::run($conf);

if (%result) {
  if ($result{'cb'} != 1) {
    print "  Pashua returned the following hash keys and values:\n";
    while (my($k, $v) = each(%result)) {
      print "    $k = $v\n";
    }
  }
  else {
    print " You clicked cancel!";
  }
}

Of course this is a strange example -- we're not doing anything with the results, and the "print" statements won't appear in the GUI application. But that's it! Once you get the result back, you can process them however you want. If you set a "cancelbutton" as an element like we did above, then you will just get:
cb=1

Otherwise, each key will be named according to the element name you picked above, like rb1, pop, etc.
ob = /Users/ghutchis/foo.txt
foo = 1
pop = Gonzo
rb = Leopard
tf = 
cb = 0

The full example script (to paste in place of the "Doubleclickable Example" can be found here.
Next time, I'll take a a slight detour. I'll be looking at alternate tools (i.e., not full Mac applications) for running command-line tools and scripts. Any questions about using Pashua? Any suggestions for this tutorial series -- things you'd like to see?