The comments on this blog are full of questions particularly about browser plugins, and even more specifically about NPAPI plugins.  Now, I don’t mind helping people out at all; that’s how we all learn.  However, in an effort to help everyone help each other, I wanted to bring the IRC chat room for FireBreath to everyone’s attention.

IRC Chatroom

To date, there are about 4 of us who are usually in the chatroom, and we discuss more than just FireBreath.  FireBreath is a project that combines experience with NPAPI, ActiveX/COM, and cross platform development in a fairly unique way.  We benefit from interaction with anyone working on any of these technologies.  What I’m trying to say is, feel free to bring your plugin questions of *any* type to that room.  We won’t do your work for you and we don’t promise to have an answer to every question, but we have a pretty decent understanding of the subject between us.

Where it is

The server is irc.freenode.net.  The channel is #firebreath.

See you there.

The Goal

Create HTML elements dynamically which transition appropriately when the view controller appears.

The Problem

The shipping version of TuneKit.js doesn’t give you a chance to append elements to the DOM before viewDidAppear is invoked (which is after transitionToController).

Initial Attempts

I first tried appending the child elements (using TKUtils.buildElement in a loop over appData.songs) inside the viewDidAppear callback. Obviously, the problem here is that the elements don’t exist the first time the view controller appears, so can’t nicely fade in via your defined CSS animations.

Next, I tried moving the logic that create the HTML elements into viewWillAppear. The problem here was that this method was called before the desired view controller is added to the DOM — so the element I need to append the children to doesn’t exist.

The Solution

The solution was actually pretty simple, and works like a charm; you just need to be willing to edit TuneKit.js.

Before:

1
2
3
4
5
6
7
8
9
10
11

// pre-transition methods
controller._viewWillAppear();
controller.viewWillAppear();
 
// add it to the tree
this.view.appendChild(controller.view);
 
// transition
if (previous_controller !== null) {
  this.transitionToController(previous_controller, controller);
}

After:

1
2
3
4
5
6
7
8
9
10
11

// add it to the tree
this.view.appendChild(controller.view);
 
// pre-transition methods
controller._viewWillAppear();
controller.viewWillAppear();
 
// transition
if (previous_controller !== null) {
  this.transitionToController(previous_controller, controller);
}

Conclusion

Now that TuneKit appends the view controller to the DOM before calling the viewWillAppear callback, your dynamic elements can be created before the view appears and transitionToController is invoked.

Done.

One of the least understood concepts in the Browser Plugin world is — browser plugins.  What they are, and even more: what they are not.  Probably at least once a week I answer a question somewhere on a forum or on the comments on this blog and say “You can’t do that with a plugin; you need an extension”.

Many people confuse plugins and extensions in the browser world. They sound like they should be the same thing, but in fact they are very different.

What you can do with a plugin

A plugin is, quite simply, a third party library that “plugs in” to the browser that can be embedded inside a web page using an <embed> tag or a <object> tag.  Many of them then draw pretty pictures or animations, though that’s not required.  Many allow you to talk to them through javascript, though that’s not required.  In short, a plugin affects only a specific page in which it is placed.

Examples of common plugins include:

• Macromedia Flash
• Microsoft Silverlight
• Apple Quicktime
• Adobe Reader (at least this includes a plugin in addition to the rest of the application)

Some plugins respond to a mime type and can run in place of the page, such as Adobe Reader, which allows you to view PDF files in your web browser.  Again, however, it affects only that page, and no others.  In Firefox, Chrome, Opera, and Safari, these plugins are usually called “NPAPI plugins”, since they are written using the NPAPI.  In Safari, you could also use a Webkit Plugin.  In Internet Explorer you would do this with an ActiveX Control.

What a plugin can not do

Plugins have to either handle a mime type or be embedded into a web page.  They don’t get put there automatically. They don’t create toolbars.  They don’t affect browser menus.  They don’t know about tabs, or even about other pages in the same browser process.  They don’t make coffee, tea, or hot chocolate, though they could be written to control an external appliance to do so if you really wanted.  They don’t automatically process the content of every web page loaded.

“But wait!” I hear you all cry.  “We have seen these magical things done (well, except the hot chocolate machine)”.

“Yes,” I reply.  “Those are extensions.”

Extensions

Extensions, or “add-ons”, can often do these magical things.  They can add onto the browser UI, process pages that the browser loads.  They do all sorts of things.  However, they are not the same thing as plugins; they affect the web browser itself, not really the page.  They may affect a page as well, of course.  In fact, you can even put a plugin inside an extension, at least in Firefox.  However, if you write an extension for Firefox, you’ll probably have to write it again for Chrome, Safari, and IE… one for each.  Perhaps there is a framework out there for writing portable extensions, though.  It’s not really my area of expertise, so I don’t know.

Examples of extensions / add-ons:

• DownThemAll for Firefox
• Firebug for Firefox
• Google Voice extension for Chrome
• Let there be Comic Sans for Safari

And many, many, many more.  Extensions can be written in different languages depending on the browser.  In Firefox you can write them in C++ or javascript, and on Internet Explorer you write them as special ActiveX controls called Browser Helper Objects, or BHOs.

An extension could contain a plugin, but a plugin can’t contain an extension

One very common way to install a plugin in Firefox is to use a .xpi file.  This is an extension.  It may have a NPAPI plugin inside of it, but it is still an extension.  It will not work on other web browsers, even though your NPAPI plugin may work perfectly fine on Chrome and Safari if installed in another way.

Conversely, a plugin by nature does not include an extension.

FireBreath

Nearly a year ago now I began a project called FireBreath, which is a cross-platform browser plugin architecture.  FireBreath is, frankly, awesome. You can literally get a plugin up and going in under 10 minutes if you already have everything installed.  That means you can spend your time doing other more important things, like actually developing your functionality, rather than spending all your time figuring out how to deal with the plugin APIs.

That said, FireBreath is a cross-platform browser PLUGIN framework.  It does not create extensions.  It will never be able to create extensions.  If you need an extension, you need something else.

When not to use a plugin

Finally, and this is a topic that people seem to think is a little strange coming from me, there are many cases when it is not a good idea to use a browser plugin.  In fact, a good rule of thumb is that if you can do what you need to do without one, don’t use one.

Why?

• There are no really good ways to install browser plugins that will work 100% of the time
  • XPI install only works on one profile in firefox
  • CAB install only works in Internet Explorer and is sometimes a little unreliable
  • ClickOnce works only in Windows and only if .Net is installed
  • Java installers only work reliably and consistently on Mac OS
  • MSI or EXE installers while being the best method IMHO require a little more work on the part of the user, and the average user is… less savvy than you are, shall we say.
• Plugins have to take into account a large range of hardware types
  • If you use graphics libraries such as OpenGL or DirectX keep in mind that every graphics card works a little differently with these technologies.  You will run into weird cases where your plugin doesn’t work on someone’s computer.  If your luck is like mine, that computer will belong to an executive at a fortune 500 company (yes, that happened to me.  no, it wasn’t fun)
• Plugins don’t work until they have been installed
  • This is a major limiting factor to uptake of your site.  Many users don’t want to install yet another plugin on their machine, and many get lost in the incredibly complicated task of downloading and running the installer.

Moving on

If all of those things haven’t convinced you that what you want isn’t actually a browser plugin — great!  That’s why I’m still posting about this stuff.  Despite all the reasons not to use a plugin, there are also a lot of cases where it’s a good idea. Browesr plugin development can be a lot of fun!  Good luck!

I’ve recently been using PHP a lot.  I’ve also been using VIM a lot.  So, it makes sense that I would start using the PHP remote debugger, right?  Well, the problem is (and don’t take this the wrong way), the php remote debugger plugin for vim was written in 2004, and there are a few things missing from it.  So, being the overly-easily-amused developer I am, I embarked on a quest to fix it.

DBGp python library

It didn’t take me long to realize that the python classes (vimscript doesn’t do sockets, so you have to use something like python) provided with the old plugin was not extensible enough for what I needed.  I started re-factoring it, but fortunately before I got too far I found a DBGp python library written by ActiveState.  I had to do some hacking to get it all working together — vim doesn’t deal with import statements in python well — but it turned out to be perfect for my needs.

VimDebugger README

Here is the README from the github repo:

map <F11> :DbgStepInto<CR>
map <F10> :DbgStepOver<CR>
map <S-F11> :DbgStepOut<CR>
map <F5> :DbgRun<CR>
map <S-F5> :DbgDetach<CR>
map <F8> :DbgToggleBreakpoint<CR>

Note 1: The method described here should also work in Mac OS X Leopard or Tiger, just get the appropriate versions of SIMBL / Visor.
Note 2: If you don’t want everything on my bullet list, just follow the steps appropriate for what you want to accomplish.
Note 3: I have provided .patch files, etc. at the bottom of the post for those who, like me, are a bit lazy.

What is Terminal Nirvana?

As a developer, Terminal is one of my best friends. Maybe you can relate. I have constantly been in search of the ultimate Terminal configuration, and it has ever eluded me… until now.

But what is Terminal Nirvana? Here are my criteria:

1. I want the Home / End keys to move the cursor to the front / end of the line. I grew up on Windows, and I like the keys to function this way. To me, it just makes sense. Unfortunately, KeyFixer doesn’t work in Terminal (but I highly recommend it for changing the behavior in most other apps!).
2. I don’t want Home / End to behave differently when I am in a screen session. I use screen all the time, and Home / End need to behave consistently.
3. I don’t want Home / End to do unexpected things in VIM – ever. Pressing Home / End in VIM should, at the very least, not do weird things like delete lines, whether I am in a screen session or not.
4. I want my terminal window available at all times. With as much as I use the terminal, opening Terminal.app all the time feels wasteful. There should be a better way. This is where SIMBL and Visor come in.
5. I don’t want it to show up in the Dock, or in my Command + Tab list. As useful as Terminal is, there are a lot of other useful applications around, and I use a lot of them. Since I always want Terminal open anyway, it is annoying to constantly avoid / ignore / tab over it when I am using Command + Tab to switch to another running application. Oh, and it should stay away from my Dock, too.
6. I want good, configurable colors in my shell. Fortunately, Visor takes care of this one by including TerminalColours as part of the package, so you get this one “for free.”

Sound like a tall order? It took me a few hours crawling around the web and experimenting to come up with a good solution, but I managed it in the end. Hopefully my experience can help save a few people some time in the future.

This is how I did it.

First things first

Before you go any further, make sure you have installed SIMBL and Visor. The latest versions work great in Snow Leopard with a 64-bit Terminal.app, so knock yourself out.

Home / End keys

To change the Home / End keys in Terminal.app, you are going to need to go to Terminal -> Preferences -> [Settings] -> [Keyboard]. Remember, settings are profile-specific, so you will need to make the changes to any profiles you care about. (Note: Visor uses the “Visor” profile, regardless of what you set as your default profile. What I do is rename the automatically-created “Visor” profile, configure my default profile, and then duplicate it with the name “Visor”.)

The first thing I tried was changing the keybindings to “\001″ and “\005″ per the instructions I found on Ricky Campbell’s blog. This seemed to make sense; CTRL+A and CTRL+E move the cursor to the front / end of the line in Terminal. And I thought it was working perfectly, for a few glorious moments…

Unfortunately, CTRL+A is also the key combination to start a command in screen. So when I launched screen, suddenly my home key didn’t work anymore, and I randomly started sending screen commands when I used it.

I also tried using a ~/.inputrc file and the keybindings “\033[1~” and “\033[4~” as discussed on two blogs I stumbled across while looking for an alternate solution. Now, I really thought I had the problem licked. Except, Home / End did weird things in VIM running within a screen session, and the necessity of using an additional .inputrc file was just a bit of a bummer.

Turns out Shift + Home and Shift + End  already did what I wanted, so the simplest solution of all is to just copy those keybindings already present in the Terminal settings. For good measure, I copied the “shift page up” and “shift page down” bindings to “page up” and “page down.” (Note: you can either copy-paste the existing values, or hit ESC to get the \033 value and then type the other characters manually.)

Terminal key bindings:

• home
  • Value: \033[H
• end
  • Value: \033[F
• page up
  • Value: \033[5~
• page down
  • Value: \033[6~

Fixing VIM in screen

Okay, almost there with the keybindings. If you run VIM inside a screen session, you will notice that Home deletes the current line, and using the arrow keys while in insert mode inserts A / B / C / D rather than moving the cursor. Not good.

A little tweak to your existing ~/.vimrc file will fix it right up (or, if you don’t have an existing ~/.vimrc, create it). (Note: the easiest way to get the proper escape characters is to enter insert mode, and hit CTRL+V followed by the Home or End key. This will add the ^[ escape character, as well as the [F or [H characters. Do the same thing for CTRL + O to get the ^O escape character.) By using CTRL+O on the imap lines, we make the Home / End keys work the same way in insert mode or command mode.

As an added bonus, this fixes the arrow keys while in insert mode. Though, to be honest, I have no idea why…

1
2
3
4
5
6
7

""" ~/.vimrc
 
""" Fix home and end keybindings for screen
map ^[[F $
imap ^[[F ^O$
map ^[[H g0
imap ^[[H ^Og0

Making Terminal always available

This one was actually pretty simple. Using SIMBL and Visor (both compatible with 64-bit Terminal at the time of this writing) you can get Terminal to dock to the top / side / bottom of your screen, and configure it to open with a keystroke you can define.

My keystroke is Command + Esc (turn off Front Row first, if you hate it as much as I do). Once Terminal has been launched for the first time (thus creating the Visor window), this keystroke gets you in from anywhere, or hides it when you are done.

Hiding the Dock icon, and removing Terminal from the Command + Tab list

This is the most involved step, but it also provides one of the biggest benefits in my mind. Most of the information here comes from a MetaSkills blog article.

In order to accomplish this, the LSUIElement key in Terminal’s Info.plist must be set to “1″. This disables the Dock icon and removes the application from the Command + Tab list. Don’t want to completely prevent Terminal from ever functioning like a normal application? The quick solution is to create new application “VisorTerminal.app” which is used for Visor, while leaving Terminal.app alone to function as normal. (This is actually a good thing, because another side-effect of setting LSUIElement : 1 is you no longer have anything change in the menubar when you are in your application… ie, you can’t click on VisorTerminal next to the Apple icon, and go into Preferences.)

Create a new VisorTerminal.app

Duplicate the existing Terminal.app.

1

cp -r /Applications/Utilities/Terminal.app /Applications/Utilities/VisorTerminal.app

Once you have duplicated Terminal.app, you need to change a few bundle identifiers in your new application so the two appear as distinct entities to Mac OS X. In other words, change “Terminal” to “VisorTerminal” in a few places. This is also when you add LSUIElements : 1.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<!-- /Applications/Utilities/VisorTerminal.app/Contents/Info.plist -->
...
<key>CFBundleDisplayName</key>
<string>VisorTerminal</string>
...
<key>CFBundleIdentifier</key>
<string>com.apple.VisorTerminal</string>
...
<key>CFBundleName</key>
<string>VisorTerminal</string>
...
<!-- Note: Put this right before the closing </dict></plist>
     at the end of the file -->
<key>LSUIElement</key>
<string>1</string>
...

At this point, rather than entering my preferences all over again, I elected to copy my Terminal.app preferences. Repeat this step any time you make preference changes that you want to copy over. (Note: using a symlink does not seem to work. If you make changes while in VisorTerminal, such as changing the Visor hotkey, the modified file is saved over your symlink.)

1

cp ~/Library/Preferences/com.apple.Terminal.plist ~/Library/Preferences/com.apple.VisorTerminal.plist

Modify Visor to use VisorTerminal.app

Once your new application is created and ready to go, you need to tell Visor to activate for that application rather than Terminal.app. Apply the following very familiar tweaks to Visor’s Info.plist:

1
2
3
4
5
6
7
8
9
10
11

<!-- ~/Library/Application\ Support/SIMBL/Plugins/Visor.bundle/Contents/Info.plist -->
...
<key>BundleIdentifier</key>
<string>com.apple.VisorTerminal</string>
...
<key>ExecPattern</key>
<string>*/VisorTerminal.app/Contents/MacOS/Terminal</string>
...
<key>BundleIdentifier</key>
<string>com.apple.VisorTerminal</string>
...

Once this last step is done, you are almost there. Make sure Terminal.app and VisorTerminal.app are both closed. Now, launch VisorTerminal.app and behold its wonder!

1

open /Applications/Utilities/VisorTerminal.app

What? It didn’t work?

Let me guess. A Terminal window opened, but Visor didn’t take effect. What gives? (You may have also noticed that you don’t have an entry in your menubar… see above.)

Turns out newer versions of SIMBL don’t activate in applications with LSUIElement : 1. Apparently this is expected behavior due to the Cocoa event mechanism. But all is not lost!

You can manually inject SIMBL into an application using Apple Script.

1
2
3

tell application "VisorTerminal"
	inject SIMBL into Snow Leopard
end tell

Great, but I don’t want to do something manually every time I want a Visor window. I just want it to always be there, remember?

Use the AppleScript Editor to save this snippet as an application, and then include that application in your user startup items. Voila! When you log in, the AppleScript helper executes, which launches VisorTerminal with SIMBL injected. Visor activates, your terminal automatically hides itself, yet is always there when you want it with the push of a button. It doesn’t clutter up your Dock, your application switching, and you can still use Terminal.app as usual whenever it makes sense to do so.

Final thoughts

First off, note that this tutorial was written using SIMBL 0.9.7a, Visor 2.2, and Terminal 2.1.1 (273) on Mac OS X Snow Leopard 10.6.4. YMMV.

Secondly, my thanks to all the people who are smarter than me and figured all this out. All I did was put things together.

Third, see below for patch files and my AppleScript application.

Finally, does anyone have the following issue, and know a way around it? After setting my key bindings, when I launch Terminal for the first time, they don’t take effect. Home does nothing special. If I open a new Terminal window, the home key starts working as expected, both in the new window as well as the original window. This happens to me whether I use \001 for the control character (and this without a ~/.inputrc file) or if I use the solution described above. Slightly bothersome, but since I almost always use my Visor terminal (which doesn’t exhibit the same problem… nor did it using Visor sans any modifications discussed here) I don’t notice it too often.

Patch files: http://gist.github.com/484082
AppleScript app: HiddenVisorTerminal.zip

If you don’t know what CouchDB is, well, there are a lot of other places where you can find that out better than I could explain it.  Google it, my friends, google it.

Harder than it should be

Installing CouchDB with MacPorts should really be as easy as typing “sudo port install couchdb”.  Unfortunately, at least as of the date this was posted, it is not that easy.  The problem is that CouchDB is written in erlang, and erlang has been updated in macports to be a newer version than CouchDB 0.11 (the current stable version) supports.

I have written a post previous to this one about how to downgrade that.  Please read that and do it before proceeding with these instructions.  If you don’t — it just won’t work.

Installing CouchDB

$ sudo port install couchdb
--->  Computing dependencies for couchdb
--->  Fetching couchdb
--->  Verifying checksum(s) for couchdb
--->  Extracting couchdb
--->  Configuring couchdb
--->  Building couchdb
--->  Staging couchdb into destroot
--->  Installing couchdb @0.11.0_0
--->  Activating couchdb @0.11.0_0
########################################################################
# Changes in CouchDB 0.10.0 make 0.9.1 database files incompatible.
# See http://wiki.apache.org/couchdb/BreakingChanges for details
#
# Run the following command to install the CouchDB launchd
# startup item in order to start and re-start service automatically:
#
# sudo launchctl load -w /Library/LaunchDaemons/org.apache.couchdb.plist
########################################################################
--->  Cleaning couchdb

Don’t be alarmed; even though it says 0.10.0 as the version in the notice, that is a warning about an upgrade that (if this is a new install) doesn’t apply to us.

Add missing files

There are a couple of directories that CouchDB scans for configuration files that aren’t created by default.  We’ll create those now (this shouldn’t be critical, but it does prevent warnings.)

$ sudo mkdir /opt/local/etc/couchdb/default.d
$ sudo mkdir /opt/local/etc/couchdb/local.d

Test the configuration

$ sudo -u couchdb couchdbPassword:
Apache CouchDB 0.11.0 (LogLevel=info) is starting.
Apache CouchDB has started. Time to relax.
[info] [<0.31.0>] Apache CouchDB has started on http://127.0.0.1:5984/

If you don’t see this, try to read the error message and figure out what went wrong.  The most common problems I’ve seen deal with permissions issues, usually on /opt/local/var/log/couchdb and /opt/local/var/lib/couchdb

Start automagically

The notice above gives you a launchctl command to load the LaunchDaemon plist file; you don’t need that.  There is a much easier way:

$ sudo port load couchdb
$ curl http://127.0.0.1:5984
{"couchdb":"Welcome","version":"0.11.0"}

And we’re done!  As the couch people say, Time to relax.

I’ve been using couchdb a lot lately, and I really like it; unfortunately, someone isn’t really on the ball in the MacPorts world.  They upgraded erlang in macports to default to R14A, which breaks backwards compatibility for a *lot* of other ports, including couchdb.  We’re going to change that so that we get a version compatible with couchdb.

Downgrading erlang

The last revision that had the version of erlang that we want was 64916.  First thing we need to do is check out erlang for that revision.  I’m going to store my “local” macports repo in /Users/Shared/dports/:

$ mkdir /Users/Shared/dports && cd /Users/Shared/dports
$ svn co --revision 64916 http://svn.macports.org/repository/macports/trunk/dports/lang/erlang lang/erlang

You should now have the local repository files that you need.  Add the path to your local repository to /opt/local/etc/macports/sources.conf before the rsync line:

file:///Users/Shared/dports
rsync://rsync.macports.org/release/ports/ [default]

now run portindex to get MacPorts to see the “new” (old?) version.

$ sudo portindex /Users/Shared/dports/

now if you do “port list” you should see:

erlang                         @R13B04         lang/erlang

and you can install it simply with “sudo port install erlang”

Port install log

$ sudo port install erlang
--->  Computing dependencies for erlang
--->  Fetching erlang
--->  Attempting to fetch otp_src_R13B04.tar.gz from http://distfiles.macports.org/erlang
--->  Attempting to fetch otp_doc_man_R13B04.tar.gz from http://distfiles.macports.org/erlang
--->  Attempting to fetch otp_doc_html_R13B04.tar.gz from http://distfiles.macports.org/erlang
--->  Verifying checksum(s) for erlang
--->  Extracting erlang
--->  Applying patches to erlang
--->  Configuring erlang
--->  Building erlang
--->  Staging erlang into destroot
--->  Installing erlang @R13B04_0
--->  Activating erlang @R13B04_0
--->  Cleaning erlang

Credits

Special thanks to Joe Homs for his blog post on doing the same thing with Ruby that I was able to tweak to work with erlang!

Implementing Macros operating on sequences

Sequences give you a convenient array-like data-structure wich can be passed to macros:

#define HEAD(sequence) \
    BOOST_PP_SEQ_ELEM(0, sequence)

std::cout << HEAD((0)(1)(2)); // prints "0"

Now how can that be implemented? First there are two characters that have special status for the preprocessor: commas and parentheses.
Parentheses can be used to

• wrap expressions to be left alone by macro expansion, e.g. because they contain commas
• can be bound to macro names as parameter lists

The binding of parameter lists doesn't have to happen immediately, so the following works fine:

#define IDENTITY(x) x
#define HEAD(sequence) IDENTITY sequence
std::cout << HEAD((42)); // prints "42"

The macro-expansion here is the following:

HEAD((42))
IDENTITY (42)
42

That already works fine for a one-element sequence, but what if it had more elements:

std::cout << HEAD((42)(23));
// results in:
std::cout << 42(23);

... which is obviously wrong. We need to get rid of the rest of the sequence by going through another macro:

#define FIRST(x) x, DOESNT_EXIST
#define HEAD(sequence) FIRST sequence
std::cout << HEAD((42)(23));

This now results in:

HEAD((42)(23))
FIRST (42)(23) // FIRST binds (42)
42, DOESNT_EXIST(23)

Passing this result through another macro that takes two arguments, we can ignore the second part:

#define HEAD(sequence) IGNORE_SECOND(FIRST sequence)
#define FIRST(x) x, FOO
#define IGNORE_SECOND(x) IGNORE_SECOND_I(x) // needed for expansion of x
#define IGNORE_SECOND_I(x, _) x

Which now expands to:

HEAD((42)(23))
IGNORE_SECOND(FIRST (42)(23)) // FIRST binds (42)
IGNORE_SECOND_I(42, DOESNT_EXIST(23))
42

Getting elements by index

Now the macros we pass the comma-separated expansion to don't have to throw away the second part:

#define SECOND(sequence) IGNORE_SECOND(TAIL sequence)
#define TAIL(x) FIRST // throw away first element

... with which we get something like the following expansion:

SECOND((1)(2)(3))
IGNORE_SECOND(TAIL (1)(2)(3))
IGNORE_SECOND_I(FIRST (2)(3))
IGNORE_SECOND_I(2, DOESNT_EXIST(3))
2

Now combining that with the concatenation operator ## we can define macros that operate index-based:

#define GET_BY_INDEX(index, sequence) IGNORE_SECOND( GET_##index sequence )
#define GET_0(x) x, DOESNT_EXIST
#define GET_1(_) GET_0
#define GET_2(_) GET_1
// ...

... which could lead to the following expansion:

GET_BY_INDEX(2, (1)(2)(3)(4))
IGNORE_SECOND(GET_2 (1)(2)(3)(4))
IGNORE_SECOND_I(GET_1 (2)(3)(4))
IGNORE_SECOND_I(GET_0 (3)(4))
IGNORE_SECOND_I(3, DOESNT_EXIST(4))
3

Counting elements

To get the size of a sequence the elements in it need to be counted. The trick here is that substitution for macros that take arguments stops if there are no parameter-lists left that could be bound, so the following:

#define SIZE(sequence) SIZE_0 sequence
#define SIZE_0(_) SIZE_1
#define SIZE_1(_) SIZE_2
#define SIZE_2(_) SIZE_3
// ...

would expand SIZE((1)(2)) to SIZE_2. All that is left then is to map that name to a number:

#define SIZE(sequence) \
    CONCAT(SIZE_, SIZE_0 sequence) // concatenate SIZE_ with SIZE_N
#define CONCAT(a, b) CONCAT_I(a, b) // allow for macro expansion
#define CONCAT_I(a, b) a ## b
#define SIZE_SIZE_0 0
#define SIZE_SIZE_1 1
#define SIZE_SIZE_2 2
// ...

... which would lead to expansions like:

SIZE((1)(2))
CONCAT(SIZE_, SIZE_0 (1)(2))
CONCAT_I(SIZE_, SIZE_0 (1)(2))
CONCAT_I(SIZE_, SIZE_1 (2))
CONCAT_I(SIZE_, SIZE_2)
SIZE_ ## SIZE_2
SIZE_SIZE_2
2

- Georg

Second to VIM, however, I have always been very impressed with TextMate. There are features in TextMate that just make me happy.  My favorate is the “Go to file…” option (Command-T).  For those of you who aren’t familiar with it, when you press Command-T in TextMate a little popup window appears.  You type part of the filename that you are looking for and TextMate displays all files in your project that contain that string.

In my (not so) humble opinion, this has got to be about the best project management tool that has ever been conceived.  The problem, however, is that TextMate only works on Mac!  Granted, I have in recent years migrated to where I do most of my work on a Mac, but when I find myself working on Windows or Linux, I need my text editor!  That’s where VIM comes in.

VIM is about the most extensible editor I’ve ever used, and that is one thing I love about it.  Granted, there are disadvantages to it — the learning curve is heavy, for one.  But, once you figure out how to do things, it’s great.  However, it definitely is missing this “Go to file…” like ability.  This has bothered me for months, but only today have I finally found an adequate solution.

The Plugin is called Fuzzy Finder.  At first glance, it seems like it almost does what we need, but not quite.  However, combined with the Project plugin, you can come pretty darn close to TextMate’s “Go to file…” feature.

My purpose here isn’t to teach you how to use the project plugin, since there already exists plenty of documentation.   I will give you a few tips, however.

When you create an entry in your project list (\C), it asks you several questions:

• “Enter the name of the Entry:” – This can be any name you wish
• “Enter the Absolute Directory to Load:” – This should be the root path for your project
• “Enter the CD parameter:” – This is the most useful option for us, but probably the least understood.
• “Enter the File Filter: ” – I usually leave this blank, but you can use it to select which files to find

The trick that I have found is that if you specify the same path for the Absolute Directory and the CD parameter, when you open files in your project vim will use that as its CWD.

So now we have a project and we can browse the files.  We can also do fast searches in the project pane; simply use “/” to search for filenames.  However, this still isn’t quite what we wanted.

The next step is to install the Fuzzy Finder plugin. Fuzzy Finder is set up to let you quickly navigate a directory tree, but it also has some other unique features that make it ideal for what we want.  To open Fuzzy Finder to find a file, the command you want is “:FufFile”.  This will pull up the Fuzzy Finder mini-dialog.

However, this still isn’t quite what we want; it does let us navigate quickly with filters, but we want to quickly search through all files in the directory!  Well, as it turns out, FuzzyFinder supports wildcards; not just “*”, but also the less often seen “**”, which means “in all subdirectories”.  So, we can then do “:FufFile **/” to tell it to start searching there.

Depending on the size of your directory, this can be a bit slow — it’s not perfect.  However, you’ll find that this way you can very quickly search through your files to open the one you want — almost the same way you would in TextMate.  Keep in mind that this relies on where our CWD is, so you can use VIM’s lcd command to move to the root of where you want to search.

Now, typing “:FufFile **/” all the time is a little cumbersome, so you may want to add a shortcut.  If you really want it to be just like textmate, you could probably set Meta-T to open it, but I prefer to leave that for MacVim which uses it to open tabs.  Instead, I use the following:

nmap <leader>ff :FufFile **/<CR>

In my configuration this means that I just have to type “\ff” to have Fuzzy Finder pop up so that I can quickly open the file I want.  I also map \fb to Fuzzy Finder’s buffer search to quickly switch to another file in the buffer (“nmap <leader>fb :FufBuffer<CR>”).

Anyway, I hope this helps someone!

In a pure C++ world we can generate interfacing or glue code between different components or interfaces at compile time, using a combination of template-based compile-time and runtime-techniques (to e.g. mostly automatically marshall to/from calls using legacy types).

When having to interface C++ applications with Objective-C/Cocoa for GUI, system integration or IPC though, things become harder due to the less strict typing – yet often not more then a flat repetitive interface layer is needed: thin bridging delegates have to be defined or conversion code to language bridging calls has to be written.

If you have to deal with interfaces of non-trivial size and want to avoid script-based code generation this quickly becomes cumbersome and is just a pain every time refactorings have to take place. Using a combination of (template) metaprogramming and the Objective-C runtime library, it should be possible to reduce the amount of code considerably…

As i didn’t get any answers that were satisfactory for me, i started on a prototype.

The following is an overview on the idea behind the prototype.

Motivation

What annoyed me most is that every time i just need to get some events of an Objective-C instance to some C++ instance, i need to create a separate Objective-C class and manually forward from there to the target (C++) object.

Lets say we have the following informal delegate protocol:

1

- (NSString*)concatString:(NSString*)s1 withString:(NSString*)s2;

Currently i have to first create an Objective-C instance:

1
2
3
4
5
6

@interface Glue : NSObject {
    CppClass* instance;
}
-(id)initWithCppInstance:(CppClass*)ins;
-(NSString*)concatString:(NSString*)s1 withString:(NSString*)s2;
@end

… with the appropriate implementation:

1
2
3
4
5
6
7
8
9
10
11
12

@implementation Glue
-(id)initWithCppInstance:(CppClass*)ins {
    if(self = [super init])
        instance = ins;
    return self;
}
-(NSString*)concatString:(NSString*)s1 withString:(NSString*)s2 {
    const std::string s =
        instance->concatStrings(toStdString(s1), toStdString(s2));
    return toNsString(s);
}
@end

Then i still have to take care of holding and initializing that Objective-C instance in the C++ instance, with possibly additional work for opaque pointers because i don’t want to bring Objective-C into the C++ header.

Objective-Glue

The idea was that there should be a way to at least cut down on the amount of code and to mostly automatically generate the bridging code.

I now found some time and came up with a basic prototype. Given the following class definition:

1
2
3
4
5
6

struct CppClass {
    std::string concatStrings(const std::string& s1, const std::string& s2) const
    {
        return s1+s2;
    }
};

… a suitable delegate can be build as follows:

1
2
3
4

CppClass cpp;
og::ObjcClass objc("MyGlueClass");
objc.add_handler<NSString* (NSString*, NSString*)>
       ("concatString:withString:", &cpp, &CppClass::concatStrings);

Here the explicit template parameter to add_handler() specifies the Objective-C signature, the first parameter specifies the method name and the last two pass the C++ instance and the method to call on it.

Free functions can also be used:

1
2

objc.add_handler<NSString* (NSString*, NSString*)>
       ("concatString:withString:", &concatStrings);

Boost.Function objects can also be passed.

The Objective-C instance can then be called like the following:

1
2
3

id ins = objc.get_instance();
NSString* result = [ins concatString:@"abcd" withString:@"efgh"];
assert([result compare:@"abcdefgh"] == NSOrderedSame);

How?

While the Objective-C signature has to be specified explicitly even for formal protocols (as in the type encodings the type information for Objective-C classes is lost), the C++ signature can be looked up at compile time. Knowing those two signatures we can use template functions to get a suitable IMP function, that “stores” the knowledge of the signatures and does the necessary conversions.

Note: Behind the scenes, Objective-C methods are simple C functions that take two additional parameters, of type id for the instance and SEL for the method being called. These functions are called IMP or implementation functions.

Combining that with the fact that the Objective-C runtime allows to add and replace method implementations via its API, we can generate classes that call suitable IMP functions. To allow for member functions, free functions or Boost.Bind generated expressions to be invoked, functors (Boost.Function) are used to store the callees.

The functors are stored in a map in the indexed ivar section of the instance, look-up is done via the selector that IMP functions are passed.
The IMP function can then cast the retrieved pointer to the correct signature type and invoke the functor.

Generating the instance

Using the Objective-C runtime, we can generate a custom class. We first need the super-class (if any):

1
2
3

std::string superClassName = "NSObject";
std::string className      = "MyObjcClass";
id superClass = objc_getClass(superClassName.c_str());

Then we need to allocate a new class pair and register it:

1
2
3

Class myClass = objc_allocateClassPair
                    (superClass, className.c_str(), sizeof(void*));
objc_registerClassPair(myClass);

The last parameter to objc_allocateClassPair() reserves additional space per instance for a pointer, so we can store the callee map later.

Now that the class is registered, we can create an instance:

1

id myInstance = class_createInstance(myClass, 0);

To add methods, we need to use class_addMethod() if the class doesn’t have such a method yet, or method_setImplementation() to override an existing one:

1
2
3
4
5
6
7
8

std::string methodName = "concatString:withString:";
SEL mySelector = sel_registerName(methodName.c_str());
BOOL added = class_addMethod(myClass, mySelector, myImp, "");
if(!added) {
    // class already has such a method, override it
    Method m = class_getInstanceMethod(myClass, mySelector);
    method_setImplementation(m, myImp);
}

Now for expressions like [myObj concatString:s1 withString:s2], the custom implementation myImp would get called. But how do we generate a suitable IMP function?

Generating IMPs

As we know the ObjcC and the C++ signatures, we can use template specialization to get a suitable function. To avoid too much repitition, partial specialization of a template class with a static member function is used:

1
2

template<size_t Arity, bool returnsVoid, class ObjcSig, class CppSig>
struct imp;

For e.g. CppClass::concatStrings, we have an arity of 2 and it doesn’t return void. This would require the following specialization:

1
2
3
4
5
6
7

template<class ObjcSig, class CppSig>
struct imp<2, false, ObjcSig, CppSig> {
    static ??? f(id self, SEL sel, ??? a1, ??? a2)
    {
        // ... invoke Callee
    }
};

Looking up the needed forms of the ObjC and C++ arguments and return types can be done via helper meta functions using Boosts FunctionTypes and TypeTraits libraries. With those types known, f() becomes something like this:

1
2
3
4
5
6
7
8

static ObjcRetType f(id self, SEL sel, ObjcArg0 a0, ObjcArg1 a1)
{
    boost::function<CppSig> callee = lookup_callee<CppSig>(self, sel);
    return convert<PlainObjcRet, PlainCppRet> // convert<ToType,FromType>
        (callee
          (convert<PlainCppArg0, PlainObjcArg0>(a0),
           convert<PlainCppArg1, PlainObjcArg1>(a1)));
}

Note: The Plain* types denote argument or return types stripped of references and constness.

With such an approach, we can choose a suitable IMP function at compile-time:

1
2
3

typedef imp<function_arity, is_same<ReturnType, void>::value, 
            ObjcSig, CppSig> ImpType;
IMP myImp = (IMP)&ImpType::f;

Conversions

Conversions are done via a static member function of a templated struct og::converter, which allows for partial specialization in user code. It is declared as following:

1
2
3

template<class To, class From> struct converter {
    static To convert(typename boost::call_traits::param_type<From>::type from);
};

Note: param_type is a Boost utility that maps the type to the appropriate form (pass-by-value for fundamental types, pass-by-const-reference for complex types, …).

To add additional conversions, specializations of converter are added anywhere before the add_handler() call that would use them. E.g. to enable conversions from NSString to std::string the following (simplified) specialization can be added:

1
2
3
4
5

template<> struct converter<std::string, NSString*> {
    static std::string convert(NSString* from) {
        return [from UTF8String];
    }
};

Conclusion

While the prototype shows that the basic idea works, there are still some issues that need to be worked out:

• support for formal protocols
• support for properties
• support for type-encodings (in a non-painful way)
• allowing full customization of class and instance (currently dealloc is needed and no class methods supported)
• convenience for wrapping complete C++ instance as Objective-C instances?
• … probably more

For those interested, here is some background reading material:

• Objective-C Runtime Programming Guide
• Understanding the Objective-C runtime
• Objective-C Runtime Reference

As previously mentioned, this is a first prototype… so constructive input and ideas are welcome. The current source can be viewed online via a bitbucket repository.
The prototype relies on some parts of Boost and was tested with Boost 1.42.

– Georg