A Simple Perl Example
Overview
The following Perl service prepends a greeting message to the selected text. This is a trivial example in that there is no GUI interaction, does not utilize any additional Perl modules, nor does it deal with multiple pasteboard types. It does, however, illustrate the basic points to consider when implementing services with Perl.
A Simple Example: Prepend Greeting
The following code listing shows a complete Bellhop service script written in the Perl language. You can try this yourself by simply creating a Bellhop document, adding a new Perl service, and then pasting the following code directly into the editor window. Then all you have to do is activate the service using the Settings panel, and then you can invoke it from any services-aware application.
# Sample Perl service to prepend a greeting to the selected text. This # service might be labeled "Prepend Greeting" in the Services menu. # The $pbrd argument identifies the unique pasteboard name # that is reserved for the current service transaction. You will # use this name as the argument to the various methods that get # and set data from the pasteboard. sub runService { # get pasteboard my $pbrd = shift(@_); # read from pasteboard $str = Pasteboard::read_string($pbrd, $NSStringPboardType); # format new string by adding greeting $str = "Greetings from Perl: ".$str; # write new string back to pboard Pasteboard::declare_types($pbrd, [$NSStringPboardType]); Pasteboard::write_string($pbrd, $NSStringPboardType, $str); }
Listing 1: Sample Perl service
If you are familiar with the concepts and implementation details regarding system services in Mac OS X, the above script should be straightforward. If not, you can refer to the Apple developer documentation covering System Services and the More Info section of this document.
Looking at Listing 1, the first non-comment line is
sub runService
This is the entry to your service. Almost all of your runService() subroutines will follow a similar pattern: extract the pasteboard name from the argument list, read pasteboard data, operate on it, and write modified pasteboard data back.
The only argument to this function, $pbrd, is the particular pasteboard that is used for this service transaction. Each service transaction is assigned a unique service pasteboard. To actually get the name into the $pbrd variable, we must extract it from the subroutine's argument list:
# get pasteboard my $pbrd = shift(@_);
The following lines read the selection from the service pasteboard:
# read from pasteboard $str = Pasteboard::read_string($pbrd, $NSStringPboardType);
Next we manipulate the pasteboard data to modify it. We are simply going to add a greeting:
# format new string by adding greeting $str = "Greetings from Perl: ".$str;
This line simply concatenates our Perl greeting and the selected text that was read from the pasteboard. The resulting string is stored so that we can write it back to the pasteboard. This is the meat of our service.
Finally, we must write the modified data back to the pasteboard so that it is made available to the requesting application:
# Write new string back to pboard Pasteboard::declare_types($pbrd, [$NSStringPboardType]); Pasteboard::write_string($pbrd, $NSStringPboardType, $str);
These lines first inform $pbrd (our unique service pasteboard) that we are about to provide it with string data. Then we actually write the modified string to $pbrd. Again, notice that we are using the custom Bellhop Pasteboard package to deal with the Mac OS X pasteboard.