In Objective-C, methods are identified by selectors. A selector is composed of the name of the method and keywords specifying the arguments to the method. If you have two methods that are the same except for the number and/or kind of arguments they accept, Objective-C treats them as separate methods. In Ruby, a method is specified by its name alone. The sort of arguments passed to a method have no bearing on which Ruby method is called. Therefore, to support the Objective-C method calling style, MacRuby extends Ruby to create Objective-C selectors from the arguments passed to a function. The examples in this chapter are meant to explain MacRuby’s method overloading, (see the Wikipedia entry for method overloading at http://en.wikipedia.org/wiki/Method_overloading), which is not something Ruby programmers normally deal with. Look carefully at the examples. The method names are always the same, and only the expected parameters are different.

Let’s imagine that we have a Player class and that it defines a method called add_contact that takes two parameters: a name and a hash with a tags key. This method adds a new contact to the player contact list, tagging the new contact with the passed tags. We can also define another method called add_contact that takes two different parameters: a name and a hash with the location key:

class Player
  def add_contact(name, tags:contact_tags)
    @name = name
    @tags = contact_tags
    "new contact #{name} was added and tagged."
  end

  def add_contact(name, location:contact_location)
    @name = name
    @contact_location = contact_location
    "new contact #{name} was added and located."
  end
end

There are four different ways to call the add_contact method:

player = Player.new
player.add_contact('Matt', tags: ['Ruby', 'Cocoa'])  
# => new contact Matt was added and tagged.
player.add_contact('Matt', location: 'San Diego')    
# => new contact Matt was added and located.
player.add_contact('Matt')                           
# => NoMethodError: undefined method 'add_contact'
player.add_contact('Matt', tags: ['Ruby'], location: 'San Diego') # => NoMethodError:

As you can see, the method signature/selector used will determine which method to dispatch. If we want to define a method for the last two examples, we can use the following:

class Player
  def add_contact(name, options={})
    # do something with the options passed
  end
end

This is important to understand, because you will often need to use selectors in MacRuby when your code relies on Cocoa frameworks.

To help you interpret existing Cocoa documentation for use with Ruby methods, here is an extract of the NSMutableString documentation:

- (void)insertString:(NSString *)aString atIndex:(NSUInteger)anIndex

This is how you call this method using an Objective-C selector (in this case, atIndex):

"Ruby".insertString("Mac", atIndex:0)  # => "MacRuby"

Hopefully this example helps you understand how to use the Cocoa documentation to port and implement Objective-C selectors, especially in the case of delegates.

If you remember the “Hello, World!” example we wrote at the beginning of this chapter, you might remember that we passed a selector to the button action. The selector was a string with the method name, followed by a colon (the colon was needed because the method had arguments). You might wonder why we called it a selector, whereas in this section, selectors seem different.

The source of confusion is that in Objective-C, selector has two meanings. It can refer to a method signature or the unique identifier associated with a method. By the first definition, methods that take different arguments have different selectors, whereas, by the second, all methods with the same name have the same selector.

Another important part of the Ruby syntax is the concept of blocks. MacRuby has blocks as well as procs and lambdas. They are all commonly referred as closures. Let’s look at some example code to understand this powerful concept:

days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
days.each_with_index do |day, index|
  puts "day #{index + 1} of the week is #{day}"
end

Running the code above will result in the following output:

day 1 of the week is Sunday
day 2 of the week is Monday
day 3 of the week is Tuesday
day 4 of the week is Wednesday
day 5 of the week is Thursday
day 6 of the week is Friday
day 7 of the week is Saturday

days is an array on which we are calling the each_with_index method and passing it a block. A block is like the body of an anonymous method that is being passed to a defined method as a parameter. The block is invoked as the defined method executes.

In this case, the block is delimited by the do/end keywords, but you can also define blocks using curly brackets, as shown here:

days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
days.each_with_index{ |day, index|  puts "day #{index + 1} => #{day}" }

This code will generate the following output:

day 1 => Sunday
day 2 => Monday
day 3 => Tuesday
day 4 => Wednesday
day 5 => Thursday
day 6 => Friday
day 7 => Saturday

each and each_with_index are iterators—methods that invoke a block of code for each of its contained items. In the case of each_with_index, two arguments are passed to the block on each iteration: an array item’s value and its index. The block called in the previous example prints out a string, interpolating the two passed values.

When using blocks, you need to be careful about the scope you are operating on. When called, a block has access to the context it’s being called on and will operate on it. Here is a simple example:

macruby_genius = 'Laurent'
developers = ['laurent', 'josh', 'matt', 'jordan']
developers = developers.map do |dev|
  macruby_genius = dev
end
macruby_genius # => "jordan"

As you can see, each iteration of the array redefines the macruby_genius variable defined earlier. So the value assigned last remains as part of the surrounding context after the do loop ends. A block is different from a method, which implicitly creates its own local context, as shown in the following example:

macruby_genius = 'Laurent'
developers = ['laurent', 'josh', 'matt', 'jordan']
def developer_names(devs)
  devs.map do |dev|
    macruby_genius = dev
  end
end
developer_names(developers)
macruby_genius # => "Laurent"

In this case, the macruby_genius variable exists in two different contexts. Therefore, even though it is being redefined in each iteration within the developer_names method, the variable set outside of the method is not affected.

Blocks can make your code easier to read and maintain. Let’s say you want to create five new Contact instances and add them to an array.

In a different language, you might do something like this:

Contact = function(){};
contacts = [];
for (i = 0; i < 5; i++) {
  var contact = new Contact;
  contacts[i] = contact;
}

However, with MacRuby, you can just write:

# Dummy objects referenced in the example
class Contact; end

# same code as the javascript example above:
contacts = []
5.times do
  contacts << Contact.new
end

# Or you can use this shortened syntax
contacts = Array.new(5){ Contact.new }

both of which, at least in my mind, read much better than the version without blocks.

Since MacRuby 0.7.1, Objective-C APIs using C blocks are supported. Here is a simple example using Array#enumerateObjectsUsingBlock (see http://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSArray_Class/NSArray.html#//apple_ref/doc/uid/20000137-SW19):

framework 'Foundation'
array = [1, 2, 3, 4, 5]
proc = Proc.new do |obj, index, stop|
  p obj
  stop.assign(true) if index == 2
end
array.enumerateObjectsUsingBlock(proc)

Here is the output:

1
2
3
=> [1, 2, 3, 4, 5]

You might be surprised that we changed the value of stop by using #assign. The reason we cannot just use the = operator is that the Objective-C API defines stop as a pointer to a boolean value, so we have to reassign the pointer’s value to make the loop stop. Read the section called “Pointers” for more information about using pointers with MacRuby.

CPU clock speeds aren’t increasing as quickly as they used to. Instead, to scale programs and improve performance, chipset designers have to add more cores to the processors. At the same time, users expect programs to do more complicated things and to do them faster than before.

The obvious solution for a long time was to use threads. The problem with threads is that they require a lot of development attention, and if not handled properly, they can seriously affect the system performance and embed difficult-to-find bugs in programs. Threads are available, and are discussed further in this book. However, since the Snow Leopard release, Apple offers a very interesting API called Grand Central Dispatch (GCD). GCD is an API on top of the libdispatch library, which Apple open sourced.

queue = Dispatch::Queue.new('com.oreilly.guide')

queue = Dispatch::Queue.new('com.oreilly.guide')
queue.sync do
  puts 'Blocking operation...'
  sleep(3)
  puts 'done waiting!'
end
puts 'Synchronous dispatching evaluated'

queue.async do
  puts "Async call..."
  sleep(3)
  puts 'Async block done'
end
puts 'Asynchronous dispatching evaluated'

class MissileLauncher
  def initialize
    @queue = Dispatch::Queue.new('org.macruby.synchronizer')
  end
  def launch!
    # Because serial queues execute their tasks in FIFO order, we can be sure
    # that only one thread will be running the passed block at any given time.
    @queue.sync do
      # critical section: here we arm the missiles and fire them.
      puts "BOOM!"
    end
  end
end

Dispatch::Queue.concurrent(:default).async do
  # expensive calculation run concurrently
end
# which is the same as
Dispatch::Queue.concurrent.async do
  # expensive calculation run concurrently
end
# Other concurrent queues can be used calling them using
# their priority level:
Dispatch::Queue.concurrent(:low)
Dispatch::Queue.concurrent(:high)

class Future
  def initialize(&block)
    # Each thread gets its own FIFO queue upon which we will dispatch
    # the delayed computation passed in the &block variable.
    Thread.current[:futures] ||=
      Dispatch::Queue.new("org.macruby.futures-#{Thread.current.object_id}")
    @group = Dispatch::Group.new
    # Asynchronously dispatch the future to the thread-local queue.
    Thread.current[:futures].async(@group) { @value = block.call }
  end
  def value
    # Wait for the computation to finish (if not already done)
    @group.wait
    # then just return the value in question.
    @value
  end
end

result = Future.new do
  p 'Engaging delayed computation!'
  sleep 2.5
  42 # Your result would go here.
end

# Then to fetch the calculation result:
result.value # => 42

class Array
  def parallel_map(&block)
    result = []
    # Creating a group to synchronize block execution.
    group = Dispatch::Group.new
    # We will access the `result` array from within this serial queue,
    # as without a GIL (Global Interpreter Lock) we cannot assume array access 
    # to be thread-safe.
    result_queue = Dispatch::Queue.new('access-queue.#{result.object_id}')
    0.upto(self.size) do |idx|
      # Dispatch a task to the default concurrent queue.
      Dispatch::Queue.concurrent.async(group) do
        temp = block[self[idx]]
        result_queue.async(group) { result[idx] = temp }
      end
    end
    # Wait for all the blocks to finish.
    group.wait
    result
  end
end

$ macgem install dispatch

require 'dispatch'
job = Dispatch::Job.new { slow_operation }
job.value # => “wait for the result”

require 'dispatch'
job = Dispatch::Job.new { slow_operation }
job.value do |v|
  "operation result: #{v} - asynchronous dispatched!"
end

require 'dispatch'
job = Dispatch::Job.new
job.add { slow_operation(a) }
job.add { slow_operation(b) }
job.add { slow_operation(c) }
job.join
job.values # =>[result_a, result_b, result_c]

require 'dispatch'
job = Dispatch::Job.new
@scores = job.synchronize Hash.new
[user1, user2, user3].each do |user|
  job.add{ @scores[user.name] = calculate(user) }
end
job.join
@scores[user1.name] # => 1042
@scores[user2.name] # => 673
@scores[user3.name] # => 845

start = Time.now
25.times do
  sleep(1)
end
puts "Took #{Time.now - start} seconds"
# => Took 25.011652 seconds

require 'dispatch'
start = Time.now
25.p_times do
  sleep(1)
end
puts "Took #{Time.now - start} seconds"
# => Took 13.028822 seconds

require 'dispatch'
locations = ["San Diego", "Chicago", "New Orleans", "Paris", "Singapore"]
locations.p_each do |location|
  # expensive calculation
  location.update_stats
end

$ macruby -rdispatch -e "puts [].methods.grep(/^p_/)"
# => p_each
# => p_each_with_index
# => p_map
# => p_mapreduce
# => p_find_all
# => p_find

require 'dispatch'
map_reduce = (0..1_000_000).p_mapreduce(0){|n| Math.sqrt(n)}
map_reduce # => 666667166.393145

require 'dispatch'
map_reduce = (0..10_000).p_mapreduce([], :<<) do |n|
  Math.sqrt(n)
end

map_reduce = (0..10_000).inject([]) do |sum, n|
  sum << Math.sqrt(n)
end

require 'benchmark'

# Monte Carlo method to find an estimated version of Pi
# For more info, read: http://en.wikipedia.org/wiki/Monte_Carlo_method
def estimated_pi(repetitions)
  inside = 0
  repetitions.times do
    inside += 1 if (Math.sqrt(rand**2+rand**2) < 1)
  end
  ((4*inside))/repetitions.to_f
end

n = 50_000
Benchmark.bm(7) do |x|
  x.report("times:")   { n.times do estimated_pi(200) end }
  x.report("p_times:") { n.p_times do estimated_pi(200) end }
end

             user     system      total        real
times:   6.030000   0.010000   6.040000 (  6.149780)
p_times:  6.300000   0.020000   6.320000 (  3.576102)

OS X ships with a security facility called sandbox. Sandbox restricts a process’s access to resources. For instance, you can sandbox your application so it doesn’t access the Internet or the local network, or can’t read or write to disk. The sandboxing applies to your entire application, including C extensions or Cocoa APIs you might be using. By using the sandbox facility in your application, you limit potential damage that can happen if a vulnerability in your application is exploited.

MacRuby exposes the Sandbox class to make easy use of the facility. The class comes with five sandboxing profiles:

You can also define your own profiles and load them. Check the API for more information.

To apply a sandbox profile, you just need to call #apply! on the profile. Here is an example:

require 'open-uri'
begin
  Sandbox.no_internet.apply!
  open('http://www.macruby.org')
rescue SystemCallError => exception
  puts exception
end

If you execute the preceding code, you will get the following output: Operation not permitted - connect(2).

Because MacRuby runs inside the Objective-C runtime, you can directly call Objective-C and C code using the Ruby syntax. However, some API symbols of frameworks or libraries cannot be introspected at runtime, usually because they are ANSI C symbols denoting nonobject-oriented items such as constants, enumerations, structures, and functions. Apple has provided Objective-C bridges and languages with a way to access these symbols nonetheless. This tool is called the Objective-C Bridges Metadata Generator, or BridgeSupport for short. Apple started shipping BridgeSupport in Mac OS 10.5 Leopard. The project is open source and you can download the latest version or the source code directly from macosforge.org.

BridgeSupport comes with XML files describing the C symbols for the system frameworks. But what if you want to use your own Objective-C/C code or a third-party framework or library? It’s actually very simple. BridgeSupport ships with a command-line tool that allows you to create XML files for your symbols.

Let’s pretend I would like to use a framework called FooBar and that this framework uses constants, so I can’t access them from MacRuby directly. The easiest way to make the framework compatible is to generate a BridgeSupport file and to add it to the framework as follows:

$ gen_bridge_metadata --64-bit -f ~/Desktop/FooBar.framework/
        -o ~/Desktop/FooBar.framework/Resources/BridgeSupport/FooBar.bridgesupport

You can see all the options by entering the following:

$ gen_bridge_metadata --help

In this example, we use the --64-bit flag to generate 64-bit annotations and the -f (framework) flag to specify that we are generating a support file for a framework. Finally, we use the -o (output) flag to save the file directly in the framework.

The BridgeSupport folder might not exist inside your framework. No big deal—just make sure to create it before generating the support file:

$ mkdir -p ~/Desktop/FooBar.framework/Resources/BridgeSupport

A BridgeSupport can be installed in one of the following locations:

For more information about BridgeSupport, check out the manual page by entering the following:

$ man gen_bridge_metadata

Mac OS X version 10.5 and later ship with a framework called Scripting Bridge. This framework allows developers to communicate with scriptable applications directly from within their code. Before Mac OS X version 10.5, developers had to use AppleScript scripts to send and handle Apple events. Using this new framework, MacRuby developers can interact directly with applications such as iChat, iTunes, iPhoto, iCal, Keynote, and so on.

A OS X application is said to be scriptable when it exposes a dictionary of Apple events. These events are hooks into the application. The easiest way to see which applications are scriptable and what APIs they expose is to use the AppleScript Editor application. Open AppleScript Editor and click File → Open Dictionary. Choose iTunes and browse the API (Figure 8.1, “The AppleScript Editor”).

Figure 8.1. The AppleScript Editor

OS X also has a series of command-line tools to inspect scriptable applications and show the available methods. The primary tool is called sdef (scripting definition extractor), which extracts the scripting definition of an application. You can give it a try in your terminal by entering the following:

$ /usr/bin/sdef /Applications/iTunes.app

The result is a long XML file describing an Apple event dictionary. The challenge is that some of these definitions use nonobject-oriented items such as constants and enumerations. So what you need to do next is create a BridgeSupport file (the section called “Using Objective-C or C Code”) to make sure you can use the full API from MacRuby.

To create a BridgeSupport file, use the sdp command. sdp is an sdef processor:

$ sdef /Applications/iTunes.app | sdp -fh --basename iTunes

The previous command generates a scripting definition for iTunes and pipes it to the scripting processor. The processor generates a Scripting Bridge Objective-C header and sets the base name of the generated header file to iTunes. The result is a file called iTunes.h that we can convert into a BridgeSupport file using gen_bridge_metadata:

$ gen_bridge_metadata -c '-I.' iTunes.h > iTunes.bridgesupport

Now we have a BridgeSupport file and are ready to start playing with the Scripting Bridge framework to control iTunes. Turn off iTunes, write the following code in a file, and execute it from the command line:

framework 'Foundation'
framework 'ScriptingBridge'

itunes = SBApplication.applicationWithBundleIdentifier("com.apple.itunes")
load_bridge_support_file 'iTunes.bridgesupport'
itunes.run
itunes.playpause

If everything goes well, iTunes is initialized and starts playing.

At home, I have a MacMini in my living room. In my bedroom, I set up a pair of speakers connected via an AirPort Express. What’s nice with this setup is that I can stream music from my MacMini to my speakers and even control what music is played via my iPhone.

Using MacRuby, I decided to write a small script that would start iTunes and play a special playlist every morning to wake me up slowly. Here is the script in question:

#!/usr/local/bin/macruby
framework 'Foundation'
framework 'ScriptingBridge'

itunes = SBApplication.applicationWithBundleIdentifier("com.apple.itunes")
load_bridge_support_file 'iTunes.bridgesupport'
itunes.run
itunes.stop
library = itunes.sources.find{|source| source.name == 'Library'}
playlist = library.userPlaylists.find do |playlist|
  playlist.name == 'morning'
end
playlist.playOnce(false) if playlist

The script is pretty straightforward. After starting iTunes (if it is not already started) and stopping any item already playing, the script finds the music library and then finds the playlist named morning. If the playlist is found, it is then played.

The AppleScript Editor doesn’t always show all the different available methods, and the documentation might not reflect the options you need. The best way to introspect the available classes is to read the header file or use the interactive command:

$ macirb --simple-prompt
>> framework 'Foundation'
=> true
>> framework 'ScriptingBridge'
=> true
>> itunes = SBApplication.applicationWithBundleIdentifier("com.apple.itunes")
=> #<ITunesApplication:0x200c5bce0>
> (itunes.methods(true, true) - Object.new.methods(true, true)).sort
=> [:EQEnabled, :EQPresets, :EQWindows, :activate, :"add:to:", :backTrack,
 :browserWindows, :"childWithClass:code:keyForm:keyData:",
 :"childWithClass:code:keyForm:keyData:length:type:",
 :"childWithClass:code:keyForm:keyData:type:",
 :"childWithClass:code:keyForm:keyDesc:",
 :classForScriptingClass, :classNamesForCodes, :classesForScriptingNames,
 :codesForPropertyNames, :context, :convert, :currentEQPreset,
 :currentEncoder, :currentPlaylist, :currentStreamTitle, :currentStreamURL,
 :currentTrack, :currentVisual, :delegate, :descriptionForSpecifier,
 :eject, :elementArrayWithCode, :"elementWithCode:ID:",
 :"elementWithCode:atIndex:", :"elementWithCode:named:", :encodeWithCoder,
 :encoders, :fastForward, :fixedIndexing, :frontmost, :fullScreen, :get,
 :"initWithApplication:specifier:", :initWithBundleIdentifier,
 :"initWithClass:properties:data:", :initWithCoder, :initWithContext,
 :"initWithContext:specifier:", :initWithData,
 :"initWithElementCode:properties:data:", :initWithProcessIdentifier,
 :initWithProperties, :initWithURL, :isRangeSpecifier, :isRunning,
 :lastError, :launchFlags, :mute, :name, :nextTrack, :openLocation, :pause,
 :"play:once:", :playerPosition, :playerState, :playlistWindows,
 :playpause, :positionAfter, :positionBefore, :previousTrack,
 :"print:printDialog:withProperties:kind:theme:", :properties,
 :"propertyWithClass:code:", :propertyWithCode, :qualifiedSpecifier,
 :qualify, :quit, :resume, :rewind, :run, :selection,
 :"sendEvent:id:format:", :"sendEvent:id:parameters:", :sendMode,
 :setCurrentEQPreset, :setCurrentEncoder, :setCurrentVisual, :setDelegate,
 :setEQEnabled, :setFixedIndexing, :setFrontmost, :setFullScreen,
 :setLastError, :setLaunchFlags, :setMute, :setPlayerPosition,
 :setSendMode, :setSoundVolume, :setTimeout, :setTo, :setVisualSize,
 :setVisualsEnabled, :shouldCreateClasses, :soundVolume, :sources,
 :specifier, :specifierDescription, :stop, :subscribe, :timeout, :update,
 :updateAllPodcasts, :updatePodcast, :version, :visualSize, :visuals,
 :visualsEnabled, :windows]
 >> itunes.methods(true, true).grep(/play/)
 => [:playpause, :"play:once:", :playerState, :playerPosition, :playlistWindows]

Method missing is a generic Ruby approach to catching undefined method calls and executing some code based on the undefined method name.

This is a very handy solution to wrap cumbersome Cocoa APIs. It allows you to pick out Cocoa classes you use often and create a more Ruby-like API for them. Let’s take, for example, the AddressBook framework. (see http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/AddressBook/AddressBook.html). This is an old framework that might not seem very natural at first. Here is a simple example:

framework 'AddressBook'
first_contact =  ABAddressBook.sharedAddressBook.people.first
puts first_contact.valueForProperty(KABOrganizationProperty)
=> "Apple Inc."

The code above is pretty straightforward: it loads the AddressBook framework and uses the ABAddressBook class method called sharedAddressBook to fetch an address book. It then calls the people method on the book, taking only the first person from the array that is returned (#first in Ruby is equivalent to [0]). Of course, before calling this code, I had to dig around in the documentation.

The odd API part is how you access a contact’s property. The Framework expects you to call #valueForProperty on your contact and to pass it a constant that defines the property type. By introspecting first_contact, we find that it’s an instance of the ABPerson class.

The ABPerson C Reference documentation lists all the properties available and the associated constants:

CFStringRef kABFirstNameProperty;
CFStringRef kABLastNameProperty;
CFStringRef kABFirstNamePhoneticProperty;
CFStringRef kABLastNamePhoneticProperty;
CFStringRef kABBirthdayProperty;
CFStringRef kABOrganizationProperty;
CFStringRef kABJobTitleProperty;
CFStringRef kABHomePageProperty;
CFStringRef kABURLsProperty;
CFStringRef kABCalendarURIsProperty;
CFStringRef kABEmailProperty;
CFStringRef kABAddressProperty;
CFStringRef kABPhoneProperty;
CFStringRef kABAIMInstantProperty;
CFStringRef kABJabberInstantProperty;
CFStringRef kABMSNInstantProperty;
CFStringRef kABYahooInstantProperty;
CFStringRef kABICQInstantProperty;
CFStringRef kABNoteProperty;
CFStringRef kABMiddleNameProperty;
CFStringRef kABMiddleNamePhoneticProperty;
CFStringRef kABTitleProperty;
CFStringRef kABSuffixProperty;
CFStringRef kABNicknameProperty;
CFStringRef kABMaidenNameProperty;
CFStringRef kABOtherDatesProperty;
CFStringRef kABRelatedNamesProperty;
CFStringRef kABDepartmentProperty;
CFStringRef kABPersonFlags;

Method missing allows us to define a different, potentially nicer API without having to define a method for each constant. Here is what the API will look like:

first_contact.organization # Acme Inc.
first_contact.first_name # Giana
first_contact.last_name # Aimonetti

And here is the implementation:

class ABPerson

  def method_missing(m, *args, &block)
    segments = m.to_s.split('_')
    missing_meth = segments.map{|part| part.capitalize}.join
    constant_name = "KAB#{missing_meth}Property"
    if Object.const_defined?(constant_name)
      self.valueForProperty Object.const_get(constant_name)
    else
      super
    end
  end

end

This might seem quite cryptic if you are new to Ruby and metaprogramming. Basically, we are reopening the ABPerson class and defining a method_missing method to catch our new calls. method_missing takes three arguments: the name of the method (m) as a symbol, an array of arguments (*args), and a block. In our case, our implementation converts the method passed (FirstNameProperty, for instance) to the format expected for a constant (KABFirstNameProperty). If the constant exists, the method dispatches the call using #valueForProperty and passing the constant. Otherwise, we let MacRuby raise an exception.

In this section, we will examine how to implement method missing and how it works so you can also wrap some unneeded complexity in a nice and clean API.

The following method_missing method is defined for Cocoa’s NSSpeechSynthesizer API:

framework 'AppKit'
class Greeter
  attr_reader :user

  def initialize(commands = {})
    voice_type = "com.apple.speech.synthesis.voice.Vicki"
    @voice     = NSSpeechSynthesizer.alloc.initWithVoice(voice_type)
    @user      = NSUserName()
    @commands  = {:hello => "Hello there #{user}, how are you today?",
                  :bye   => "Adios #{user}, come back soon!"}.merge(commands)
  end

  def method_missing(meth_symbol, *args, &block)
    command = @commands[meth_symbol]
    if command
      message = command.respond_to?(:call) ? command.call(self) : command
      @voice.startSpeakingString(message)
    end
  end
end

Open a new macirb session and copy/paste the previous code, or save it in a file and require it from macirb. You can then run a speech synthesizer session as follows:

$ macirb --simple-prompt
>> require 'method_missing_example'
=> true
>> vicki = Greeter.new
>> vicki.respond_to?(:hello)
=> false
>> vicki.hello
=> true
# greetings message is played

As you can see, we were able to call a method that doesn’t exist (hello), thanks to method_missing.

For those not used to reading Ruby code, attr_reader :user is the equivalent of a getter for the instance variable @user, making it available via the user instance method. Our initializer takes an optional argument called commands, which defaults to an empty Hash if not passed. The commands local variable is then merged with a list of default commands. This way, we can pass additional commands when creating our Greeter instance.

Finally, in the method_missing method body, we are checking whether the command object responds to the call method. If it does, we send the call method to it and save the result in the local variable message. Otherwise, we just use the command value (we do that so a command can be defined as an anonymous method). The message is then read by our @voice object.

Let’s see whether passing a new command when creating a new greeter does what we expect:

>> vicki2 = Greeter.new(:howdy => "Howdy cowboy?")
>> vicki2.howdy
# sound of the new greeting defined on the fly.

Now let’s do something a bit more tricky and pass an anonymous method that needs to be executed every single time it’s called:

>> time_cmd = Proc.new{"It's #{Time.new.hour}, #{Time.new.min} and 
>> #{Time.now.sec} seconds"}
>> vicki3 = Greeter.new(:time => time_cmd)
>> vicki3.time
# check that the seconds changed
>> vicki3.time
# time changed

Finally, let’s look at a way of optimizing the performance of our code by using some more metaprogramming. This time, we are going to define methods dynamically at runtime. Instead of always looking up the command and dynamically telling the voice what to say, once a missing method is called, we can add a new method into the class so that we never call the same missing method twice:

framework 'AppKit'
class Greeter
  attr_reader :user

  def initialize(commands = {})
    voice_type = "com.apple.speech.synthesis.voice.Vicki"
    @voice     = NSSpeechSynthesizer.alloc.initWithVoice(voice_type)
    @user      = NSUserName()
    @commands  = {:hello => "Hello there #{user}, how are you today?",
                  :bye   => "Adios #{user}, come back soon!"}.merge(commands)
  end

  def method_missing(meth_symbol, *args, &block)
    command = @commands[meth_symbol]
    if command
      self.class.send(:define_method, meth_symbol.to_s) do
        message = command.respond_to?(:call) ? command.call(self) : command
        @voice.startSpeakingString(message)
      end
      # call the newly defined method
      send(meth_symbol)
    end
  end
end

$ macirb --simple-prompt
>> require 'method_missing_example'
>> vicki = Greeter.new
>> vicki.respond_to?(:bye)
=> false
>> vicki.bye
>> vicki.respond_to?(:bye)
=> true

To optimize this code, we use some Ruby tricks you might not be aware of. The “magic” happens inside the method_missing method implementation. We already talked about method_missing, but we haven’t talked about send and define_method. To illustrate the power of these methods, I’ll explain quickly what the code example does:

def method_missing(meth_symbol, *args, &block)
  command = @commands[meth_symbol]
  if command
    self.class.send(:define_method, meth_symbol.to_s) do
      message = command.respond_to?(:call) ? command.call(self) : command
      @voice.startSpeakingString(message)
    end
    # call the newly defined method
    send(meth_symbol)
  end
end

The first thing we do is check that the missing method matches a defined command. If it does, we define the method on the fly. For that, we define the missing method on the class itself. We can’t call the define_method directly on the class, because define_method is a private method and you can’t call a private method from outside of the object. So, instead, we use the send method. The send method is a way to dynamically dispatch a method by using its name as a string or a symbol. Using send, we can call define_method on the class and pass the missing method name as an argument. The block passed to define_method will become the new method’s body. Once the method is defined, we call it using send again and pass it the method name as a symbol. There is a lot going on in just a few lines of code—take some time to experiment on your own.

As you can see, after calling the bye method a first time, the method becomes defined and the Greeter instance knows that it can respond to it.

Method missing is a very powerful tool and, like most metaprogramming tricks, needs to be used with care. Read more on Ruby metaprogramming to see all the interesting possibilities that are available to you.

In the block example earlier in this chapter, we discussed that when using Objective-C or C APIs we might have to deal with pointers. MacRuby exposes a Pointer object that allows you to allocate memory of a given type to a given number of elements. To create a pointer to a float value, for instance, you can choose one of the two constructor options:

pointer = Pointer.new(:float)
# or
pointer = Pointer.new_with_type(:f)

Table 8.1, “Available data types” shows available data types. The list can also be found on Apple’s website (see http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Introduction/Introduction.html).

You can dereference the pointer the same way you access an array in Ruby.

You can also have a pointer to multiple values. Here is how you create a pointer with bounds:

pointer = Pointer.new(:float, 4)
pointer[0] = 1.0
pointer[1] = 2.0
pointer[2] = 3.0
pointer[3] = 4.0
pointer[0] # => 1.0
pointer[1] # => 2.0
pointer[2] # => 3.0
pointer[3] # => 4.0

To assign a value to the pointer, you can use one of these two methods:

pointer.assign(3.2)
# or
pointer[0]= 3.2

When you use [] and []=, you must be careful not to try to access or set a value out of bounds. Unfortunately, there is no way to find out a pointer’s bounds.

Dereferencing pointers is pretty straightforward and was shown earlier:

pointer = Pointer.new(:integer)
pointer.assign(42)
pointer[0] # => 42

You can also offset pointers using the + and the - methods:

pointer = Pointer.new(:long, 10)
10.times{|i| pointer[i] = i }
pointer2 = pointer + 2
pointer2[0] # => 2
pointer2[1] # => 3
pointer2[2] # => 4

One situation that requires offsetting is when you are using a read method that accepts a pointer of bytes and returns the number of bytes actually read. You can set a pointer, pass it to the method, offset it, and pass it again. Here is a dummy example of such an API:

ptr = dataOut;
fakeAPI(dataIn, dataInLength, ptr, dataOutAvailable
        &dataOutMoved);
ptr += dataOutMoved;
dataOutAvailable -= dataOutMoved;
otherAPI(ptr, dataOutAvailable, &dataOutMoved);

Two types of Objective-C pointers are not directly supported by MacRuby: void pointers and unknown type pointers (also called unsigned pointers). Let’s look at how to work with these types.

extern AXError AXUIElementCopyAttributeValue (
       AXUIElementRef element,
       CFStringRef attribute,
       CFTypeRef *value);

framework 'ApplicationServices'
pid = 433
safari = AXUIElementCreateApplication(pid)
titlePtr = Pointer.new(:id)
err = AXUIElementCopyAttributeValue(safari, "AXTitle", titlePtr)
p titlePtr[0] # => "Safari"

callback = Proc.new do |stream, client_callback_info, number_of_events,
                        paths_pointer, event_flags, event_ids|
  puts paths_pointer[0] # => 0
end

paths = [File.expand_path('~/tmp')]
stream = FSEventStreamCreate(KCFAllocatorDefault, callback, nil, paths,
                             KFSEventStreamEventIdSinceNow, 0.0, 0)
FSEventStreamScheduleWithRunLoop(stream, CFRunLoopGetCurrent(), KCFRunLoopDefaultMode)
FSEventStreamStart(stream)

NSRunLoop.currentRunLoop.runUntilDate(NSDate.distantFuture)

void mycallback(
    ConstFSEventStreamRef streamRef,
    void *clientCallBackInfo,
    size_t numEvents,
    void *eventPaths,
    const FSEventStreamEventFlags eventFlags[],
    const FSEventStreamEventId eventIds[])
{ }

callback = Proc.new do |stream, client_callback_info, number_of_events,
                        paths_pointer, event_flags, event_ids|
  paths_pointer.cast!("*") # cast as a string pointer
  puts paths_pointer[0] # => /Users/mattetti/tmp/
end

paths = [File.expand_path('~/tmp')]
stream = FSEventStreamCreate(KCFAllocatorDefault, callback, nil, paths,
                             KFSEventStreamEventIdSinceNow, 0.0, 0)
FSEventStreamScheduleWithRunLoop(stream, CFRunLoopGetCurrent(), KCFRunLoopDefaultMode)
FSEventStreamStart(stream)

NSRunLoop.currentRunLoop.runUntilDate(NSDate.distantFuture)

glVertexPointer(3, GL_FLOAT, 3, (void *) 12)

glVertexPointer(3, GL_FLOAT, 3, Pointer.magic_cookie(13))

void* TISGetInputSourceProperty (
   TISInputSourceRef inputSource,
   CFStringRef propertyKey
);

framework 'Cocoa'

keyboard = TISCopyCurrentKeyboardInputSource()
keyboard_name = TISGetInputSourceProperty(keyboard, KTISPropertyLocalizedName)

framework 'Cocoa'

keyboard = TISCopyCurrentKeyboardInputSource()
keyboard_name = TISGetInputSourceProperty(keyboard, KTISPropertyLocalizedName)
keyboard_name.to_object #=> "U.S."

A book about MacRuby cannot be complete without mentioning compilation. MacRuby offers two types of compilation: JIT and AOT compilation.

Here is the simplest AOT example—save the following line of code in a file called hello_world.rb:

p ARGV.join(' ').upcase

Or, using the command line, create the file and its content:

$ echo "p ARGV.join(' ').upcase" > hello_world.rb

The code takes all the passed arguments, joins them together separated by a space, and makes the result string uppercase.

Our “program” source code is now ready, so let’s compile it using the MacRuby compiler command line tool, called macrubyc:

$ macrubyc hello_world.rb -o macruby_says

The -o option defines the output file. We can now execute our newly compiled program:

$ ./macruby_says hello world
# => "HELLO WORLD"

Looking at the macrubyc help, we can see that many other options are available:

$ macrubyc --help
Usage: macrubyc [options] file...
    -c                               Compile and assemble, but do not link
    -o <file>                        Place the output into <file>
        --static                     Create a standalone static executable
        --framework <name>           Link standalone static executable with given 
                                     framework
        --sdk <path>                 Use SDK when compiling standalone static 
                                     executable
        --dylib                      Create a dynamic library
        --compatibility_version <VERSION>
                                     Compatibility Version for linking
        --current_version <VERSION>  Current Version for linking
        --install_name <NAME>        Install Name for linking
    -C                               Compile, assemble, and link a loadable object 
                                     file
    -a, --arch <ARCH>                Compile for specified CPU architecture
    -v, --version                    Display the version
    -V, --verbose                    Print every command line executed
    -h, --help                       Display this information

If you look at the contents of a compiled MacRuby application package, you might notice some .rbo files. These files are compiled and loadable object files generated using the equivalent of the following command:

$ macrubyc -C -o file.rbo file.rb

MacRuby can then load the file directly without having to reevaluate it.

In most cases, you will use Xcode to develop your application, and the Xcode templates come with a target that does all the work for you. It turns out that there isn’t much to do to compile an app. If you open an existing MacRuby project in Xcode and look at the project’s target information, you will see that the only thing the target does is to call macruby_deploy as such:

$ /usr/local/bin/macruby_deploy --compile --embed

Because no arguments are passed to define the application-bundle path, macruby_deploy relies on two environment variables set by Xcode to define the location of the bundle: TARGET_BUILD_DIR and PROJECT_NAME.

When called with the --compile option, macruby_deploy compiles all the Ruby files available in the resources folder. Xcode copies the source files to this folder automatically for you when you build your project, before calling the external script. These files are compiled as .rbo files that are loaded by the rb_main.rb file.

When the --embed option is set, the MacRuby framework is copied to the application bundle, freeing the application from the need to have MacRuby installed on the user’s system. As part of this process, the linkage is also modified so the compiled code doesn’t break when it’s run on a different machine.

Another useful option that you might need to use when compiling an application from Xcode using macruby_deploy is --no-stdlib. It allows you to make your application smaller by not embedding Ruby’s standard library when embedding MacRuby. If you don’t rely on any libraries from the standard library, it’s recommended that you use this option. If, however, you do rely on a library from the Ruby standard library, you can tell macruby_deploy to embed only specific libraries using the --stdlib option. It takes the names of one or more libraries. You can also embed Ruby gems libraries, as explained in Chapter 13, Using Ruby Third-Party Libraries.

Finally, if you generate some BridgeSupport files or want to force the use of your versions, you can use the --bs option to embed them.

The way compilation currently works in Xcode is that you need to run the second target after building your project. In other words, you will usually develop without compiling. When you are ready, change the target to use the provided Deployment scheme, which calls macruby_deploy, which itself might call the MacRuby compiler if needed. You can see the available macruby_deploy flags by calling its help in the command line, as follows:

$ macruby_deploy --help
Usage: macruby_deploy [options] application-bundle
        --compile                    Compile the bundle source code
        --embed                      Embed MacRuby inside the bundle
        --no-stdlib                  Do not embed the standard library
        --stdlib [LIB]               Embed only LIB from the standard library
        --gem [GEM]                  Embed GEM and its dependencies
        --bs                         Embed the system BridgeSupport files
        --verbose                    Log all commands to standard out
    -v, --version                    Display the version

After you run the Deployment scheme, you can start your application manually or go back to your original scheme and build your app again. If the deployment doesn’t work as expected, you can look in Xcode’s Log navigator to see exactly what happened. You can also set the --verbose flag in the target information to see even more information about what macruby_deploy does. You can also run macruby_deploy manually in the command line, passing it the path to the application bundle file.

Finally, if things don’t seem to work properly and you can’t figure out what is going on, don’t hesitate to clean (Shift + Command + K) the project and build it again.