Chapter 3. Programming

The most important of these by far the the APR::Table class. This class is a little bit weird at first, but when you get the hang of it, you’ll start to see why it’s so useful. APR::Table basically works like both an array and a hash, depending on how you use it. There are methods that make it work as an array, and methods that make it work as a hash.

No matter how it is used, internally is stores all of its data as key/value pairs. What differentiates APR::Table from a normal Hash is how it handles collisions. A collision is when you add a value for a key that is already present in the Hash. For example:

table['Set-Cookie', 'Domain=.jujifruit.com')
table['Set-Cookie', 'Path=/')

In this example, a normal Hash will only have one key/value pair. The key is Set-Cookie, and the value is Path=/, which is the last assignment made. The previous value was overwritten. Hashes therefore manage collisions by overwriting the old value with the new one. We can say that in Hashes, keys are unique. You cannot have multiple key/value pairs that share the same key.

This is not the case with APR::Table. It’s keys are not unique. You can have multiple key/value pairs with the same key. And the weird thing is, you can still access the data as if it were a Hash. The only problem is that when you access the data for a given key, you will only get the first match. If you want all of the associated values, then you have to iterate over the table like an array. Are you confused yet? Time for an example.

Let’s look at collision handling, iteration, and hash access all at once (assume this is in a file called test.rhtml):

table = APR::Table.new(APR::Pool.new())

# Dumps the contents of a Table
def dump(t)
  puts 'Dumping Table:'
  t.each do |key, value|
    puts "  #{key}=#{value}"
  end
end

table.add('Set-Cookie', 'lp=13ds4; Domain=.jujifruit.com; Path=/')
table.add('Set-Cookie', 'edge=453fd; Domain=.jujifruit.com; Path=/')

dump(table)

puts
puts "table['Set-Cookie']='#{table['Set-Cookie']}'"

We add values with the same key, just like before. When we iterate over the table, we get:

Dumping Table:
  Set-Cookie=lp=13ds4; Domain=.jujifruit.com; Path=/
  Set-Cookie=edge=453fd; Domain=.jujifruit.com; Path=/

table[’Set-Cookie’]=’lp=13ds4; Domain=.jujifruit.com; Path=/’

See what happens? Both key/value pairs are retained. Now we have duplicate keys with unique values. When we iterate over the table like we would a normal hash, all of the key/value pairs come out. Yet if we access a single value, we only get the first match. Now you are starting the get the essence of the APR:Table: it can act like both an array and a hash at the same time.

But there’s more! APR::Table can handle collisions an alternate way. Notice we used the add() method. That method handles collisions by simply tacking on more key/value pairs. But there is also the merge() method. It handles collisions by keeping the key unique, but appending the new data to the current value. Consider the following example:

table = APR::Table.new(APR::Pool.new())

# Dumps the contents of a Table
def dump(t)
  puts 'Dumping Table:'
  t.each do |key, value|
    puts "  #{key}=#{value}"
  end
end

table.merge('Accept-Charset', 'ISO-8859-1')
table.merge('Accept-Charset', 'utf-8')

dump(table)

puts
puts "table['Accept-Charset']='#{table['Accept-Charset']}'"

Here is what we get:

Dumping Table:
  Accept-Charset=ISO-8859-1, utf-8

table[’Accept-Charset’]=’ISO-8859-1, utf-8’

See what happens here? Same key, but the value keeps growing. merge() simply appends the new value on to the end. So you can decide how you want to handle collisions by which methods you use to set the data. You can choose array-sh behavior with add(), an aggregating hash behavior with merge(), and then there is the pure hash behavior with a third method: set(). So what you really have to adjust to is just the set/get methods of APR::Table. Here are the three methods again in review:

So to be absolutely clear how these methods work indepently and together, let’s look at one final example:

table = APR::Table.new(APR::Pool.new())

# Dumps the contents of a Table
def dump(t)
  puts 'Dumping Table:'
  t.each do |key, value|
    puts "  #{key}=#{value}"
  end
end

table.add('Set-Cookie', 'lp=13ds4; Domain=.launchpad.net; Path=/')
table.add('Set-Cookie', 'edge=453fd; Domain=.launchpad.net; Path=/')
dump(table)

table.merge('Set-Cookie', 'ISO-8859-1')
table.merge('Set-Cookie', 'utf8')
dump(table)

table.set('Set-Cookie', 'wiped out')
dump(table)

Here is what we get:

Dumping Table:
  Set-Cookie=lp=13ds4; Domain=.jujifruit.com; Path=/
  Set-Cookie=edge=453fd; Domain=.jujifruit.com; Path=/
Dumping Table:
  Set-Cookie=lp=13ds4; Domain=.jujifruit.com; Path=/, ISO-8859-1, utf8
  Set-Cookie=edge=453fd; Domain=.jujifruit.com; Path=/
Dumping Table:
  Set-Cookie=wiped out

Additionally, APR::Table supports the []= operator as well, which is just another way of calling set() (as you would expect).

Now, you may still have the question “Why? — What’s the point?” Well, the previous examples give some hint to that. Notice that they all involved HTTP headers. Some HTTP headers — like Set-Cookie — can have duplicate keys. Thus in this case, APR:Table’s add() comes in handy. In other cases, some HTTP headers — like Accept-Charset — have a single key, but multiple comma-delimited values. In this case, APR:Table’s merge() comes in handy. The Apache developers recognized this and said “To keep our code clean, we need something that can easily handle both situations elegantly.” And thus the APR table (known as the apr_table_t struct in the APR C API) was born. When you do much work with HTTP headers, it doesn’t take long for you to appreciate APR:Table’s flexibility.

You’ll probably be glad to know that the remaining methods of APR::Table are straightforward. They all follow the APR table C API. The complete documentation for APR::Table is in Section 6, “The APR Table Class”.

Finally, a word on the APR::Array class. For all intents and purposes, it’s a read-only Ruby array. It has two methods: each() and size() (ideally, it also needs at least a [] operator). Currently, the only method in the API that returns an APR::Array is Request::content_languages().