Ruby Execution Context Overview
Introduction
The built-in Bellhop Ruby Execution Context plug-in executes services that are implemented in the Ruby scripting language. The plug-in uses the default Ruby installation bundled with Mac OS X (/usr/bin/ruby), and executes each service in a spawned NSTask that invokes the ruby interpreter with the service's code.
In order to allow services to be written using Ruby, the Ruby plug-in provides a dynamically loadable Ruby extension (called rbBellhop.bundle) which is automatically loaded at runtime into Ruby services that are managed by Bellhop. This extension contains definitions for three modules: Pasteboard, Panel and Finder. These modules allow Ruby scripts to interact with the pasteboard, display user interface panels, as well as invoke file functions via the Finder. The modules are explained in more detail in the Reference part of this document.
Basic Syntax
Ruby scripts can be structured quite freely; the only requirement is that the script contain a run function defined at the top level of the Ruby environment. The name of this function should be runService() and it should take a single string argument that specifies the name of the pasteboard instance responsible for a service transaction. The listing below shows the basic structure of a Ruby service script.
def runService(aPasteboard) # Put your custom Ruby code here in the runService() function. # It will automatically be invoked when a user selects the # service from the menu. end
The aPasteboard argument will be a string that specifies the unique pasteboard name for the service transaction, and is automatically passed to the function by Bellhop.
You are not required to explicitly load the Bellhop extension into your script; it is automatically loaded when the service is executed. You can, however, import any installed Ruby modules and libraries you have on your system and use them within your service using any valid Ruby syntax. You can also define your own classes, additional methods, constants, etc., so long as you provide a valid runService() function at the top level.
For a more detailed Ruby example, see the Example section of this document.
Ruby Extension Modules
As metioned above, the Bellhop Ruby plug-in implements a custom extension that allows your Ruby services to interact with the Mac OS X Services System, as well as interact with users through a set of custom user interface panels and do basic file manipulation via the Finder.
The Ruby extension implements 3 modules that you can use in your services: Pasteboard, Panel and Finder. The Pasteboard module provides methods that allow you to interact with the system pasteboard, which is used to pass data between the requesting application and your service. You can also use the Pasteboard module to write data to the standard clipboard. The Panel module provides methods that display user interface panels to users. There are panels to display alerts, prompt panels that allow your services to accept user input, and file selection and save panels. The Finder module has methods that allow you to do basic file manipulation, such as copy, move and delete files, as well as ask the Finder to open files, urls and applications.
For a complete description of the various modules, see the Reference section of this document.