I originally wrote this engine because I was generating HTML files in C++, and generating the HTML right in the C++ quickly got very hairy, besides the fact that it made the content very hard to maintain. If all you need is string interpolation, something like Boost.Format would probably be enough, but I quickly found myself wanting to include lists of objects (e.g. search results), include content conditionally, and so on.

I was inspired to write this library by the approach of the major web frameworks like django and rails.

Here's a quick example:

The result will be:

Here's how you might generate an HTML unordered list:

The result will be:

Syntax

The template syntax is fairly simple and highly influenced by Python. You can use loops, conditionals, and variables. You can use dotted notation (item.thing) for dictionary-like variables. The only data type is string.

Variable Syntax

Use {$variable_name} for variables. You can use dotted notation for sub-fields.

Loop Syntax

Note the "loop" variable that provides a counter in all loops. loop0 is zero-indexed.

If Syntax

Note that not means empty: If the variable name doesn't exist, then an exception will be thrown.

API Example

Here's a slightly more involved example of using the API, showing dot notation and loop syntax.

The output will be:

See the bitbucket wiki page for more details.

I had to go spelunking in various forums and documentation to piece together how to do this, and I never found the complete story online, so I thought I'd save any future searchers some trouble. I only did this in Visual Studio 2008, but I've done similar things in VS 2005, so it should work there also.

You should already have a WTL project with an .idl file that implements a COM server. If not, create a new WTL project with the wizard named "MyProject", and choose the option to make it a COM server.

Add an ATL Simple Object

Next, add a new class to your project, and select the type "ATL Simple Object."

Here's where you might hit your first snag. You might see the following error dialog:

ATL classes can only be added to MFC EXE and MFC Regular DLL projects or projects with full ATL support

"I'm using the ATL, you idiot!" you yell vainly at your computer screen. But alas, the compiler gods did not consider that you might want to use something as esoteric as the WTL for your GUI project, when you have the obviously superior choice of MFC.

To convince Visual Studio that yes, you do deserve to add an ATL Simple Object to your project, you've got to modify the file "VS Root/VC/VCWizards/1033/common.js". Specifically, you've got to have the function IsATLProject return true.

On the Internet, you'll see all sorts of fixes to this function, but I just cut to the chase:

Try adding the object again; this time, you should be successful. Name your class something descriptive, like "MyHandler" ( ), and accept all the defaults.

Modify the .idl file

Now go into your .idl file, and make some edits. First, import "atliface.idl", and #include "olectl.h". The top of your file should now look like this:

Now, go to your IMyHandler interface, and change the base class from IDispatch to IDocHostUIHandlerDispatch, like so:

Modify your MyHandler.h file

Go into your CMyHandler class file, and #include "Atliface.h". Next, add an entry to your COM map for IDocHostUIHandlerDispatch. The top of your file should now look something like this:

Add skeletons for the IDocHostUIHandler methods

Add skeletons for all the methods implemented by IDocHostUIHandler. You can simply copy and paste the method signatures from IDocHostUIHandlerDispatch in "Atliface.h". Now implement the method bodies so that they all return E_NOTIMPL.

Compile your code

Now compile, and make sure that everything's working.

Here's where you might hit another snag: by failing to show proper respect to the compiler gods above, you could see an obscure MIDL error when you try to compile. Even if you don't, I recommend compiling your .idl file manually just to be sure. Go to All Programs >> Visual Studio 200X >> Visual Studio Tools >> Command Prompt (this loads the command prompt with all your VS symbols defined).

Next, navigate to your source directory, and compile your .idl file:

Implement methods of interest

Now, you can implement the methods you're interested in. For example, if you want to suppress the context menu, or show your own menu in its place:

Set the handler in your web browser

In your OnCreate handler, set your handler in the web browser.

That's it. Compile and run.

If you only knew a statically typed and compiled language like C++ or Java before, and learning Python hasn't changed the way you think about programming, then check your programs for lots of type-checking code, inheritance, array indexing, and mutable variables. Look at some excellent Python code, and identify where your code diverges from it.

I've long been a fan of the WTL — I've written several programs in it, including Felix, Doc2Html, and Tag Assist — and it's great to see it getting some love.

In my opinion, the WTL is simply the best way to write Win32 programs in C++. MFC was written before Visual Studio really supported templates. One of the MFC team once said that the WTL is what they would have written if good template support had been available.

In order to get that kind of code into a test harness, I first create "characterization tests" — tests that simply verify what the code is doing. I let the code write files, connect to databases, etc. Then I gradually modify them to create a layer between the code and the outside world, which I can then manipulate for testing.

Here's a very simple example. I have a ConfigWriter class, which (duh) writes config files. The class lets you set and get various properties, and then write the config file, specifying a file name.

The class has been doing great, but now I want to modify it. Maybe I want to add functionality, or maybe I've found a bug. At any rate, before I make the changes I want to get this class into a test harness — but I want to be able to unit test it without touching the file system.

My first step is to write a unit test that confirms what the class actually does. I use EasyUnit as my unit-testing framework, but you can use any framework you're happy with.

I run the test, and it passes. Now I add a new write method, which takes a pointer to an ostream instead of a file name.

I run my unit tests, and make sure that they still work. Then I add a new unit test to test the new method:

Once I make sure they pass, I modify the write(const string &fname) method so that it calls the ostream version.

I run the unit tests, and make sure they all pass.

Now I'm ready to mock the file output. I change the ofstream in my unit test to an ostringstream:

I run the unit tests again. Now I'm able to unit test the class without touching the file system. I delete the unit test for the write(const string &fname) method.

I'll still have regression and function tests that actually write config files and test their output, but I want my unit tests to run very quickly, without affecting the "outside world."

Start by designing, coding, and testing your application in Python, using available extension modules if they save you work. This takes much less time than it would with a classic compiled language. Then benchmark the application to find out if the resulting code is fast enough. Often it is, and you're done — congratulations! Ship it!

Since much of Python itself is coded in highly optimized C, as are many of its standard and extension modules, your application may even turn out to be already faster than typical C code. However, if the application is too slow, you need to reexamine your algorithms and data structures. Check for bottlenecks due to application architecture, network traffic, database access, and operating system interactions. For typical applications, each of these factors is more likely than language choice to cause slowdowns. Tinkering with large-scale architectural aspects can often speed up an application dramatically, and Python is an excellent medium for such experimentation.

If your program is still too slow, profile it to find out where the time is going. Applications often exhibit computational bottlenecks: small areas of the source code, often between 10 and 20 percent, which account for 80 percent or more of the running time. Then optimize the bottlenecks…

I write just about all my code in Python first. Then if it's not fast enough, I profile it to find the bottlenecks. First, I try optimizing the algorithms for the bottlenecks. If it's still too slow, I try optimizing the code — things like hoisting method lookups out of the loop, replacing slower idioms like string concatenation with list joins, etc.

If it's still too slow, I'll rewrite the remaining bottlenecks in a lower-level language. I continue to profile to ensure that I'm speeding up what I think I am.

Even when I have a pretty good idea that I'm going to have to implement a certain function in a lower-level language, I'll still write it in Python first. Having the high-level implementation makes writing the lower-level one a lot easier. Plus the resulting code is likely to be cleaner and have fewer bugs.

As an example, I once wrote a file-parser in Python. It was too slow, so I rewrote some parts of it in C++. Overall, development took me about two days — a day for the Python, and a day for the C++.

Some time before, I had written a different file parser entirely in C++. The level of complexity was about the same — but this parser took me about a week to write, and I was finding bugs in it for a couple of months.

The Python-based parser was much more free of bugs; it was also a lot easier to maintain and extend, something that has been of huge value. But the real kicker was that my hybrid Python/C++ parser performed as well or better than the pure-C++ version (it's impossible to compare them directly, because they were parsing different things).

So my motto now is to aim high — put everything into a high-level language (usually Python in my case), dipping down to lower-level languages only when necessary.

So Dan would go through and hand-optimize the assembly code to get rid of those wasted cycles and squeeze out every possible lick of performance. He earned quite a decent living at it, until the mid 1980s when the work dried up.

Did his work dry up because machines had grown so fast that companies didn't care about wasted cycles anymore? No, they were just as stingy about their computer resources as they used to be. The reason why the work dried up was because the compilers eventually got so good that the amount of tuning Dan could do was no longer worth the cost.

Today, you can write assembly language that's faster than C, but you really have to know what you're doing if you want to gain much speed — C compilers today are pretty smart. Nowadays, you might drop down to assembly for a really tight loop, where every machine cycle counts, but writing an entire program in assembly is — shall we say — no longer mainstream.

There's an obvious parallel with Dan's job today: saving machine cycles by rewriting code in very high-level languages like Python and Ruby in faster, lower-level languages.

Certainly, there's still a place for this kind of optimization today. But how long will this still be the general case? It's already true that you have to know what you're doing to beat C# or Java with C/C++. Yes, C and C++ are still faster than C# and Java when you know what you're doing. But simply writing in those languages doesn't guarantee that your code'll be faster (and for simplicity's sake, I'll leave out considerations of automatically versus manually managed memory).

When JIT compiling becomes a reality for Python, it might become true for this language as well. Then we might see ever-diminishing returns on rewriting Python code in lower-level languages.

"Bare metal" programming used to mean assembly language — now it mostly means C. I for one can't wait for the day when "dropping down to the bare metal" means writing Python code!

Private members are a pain to unit test

Classes with lots of private methods and variables are a pain to unit test. The pathological case is the "iceberg class" — one public method with a void return, and lots of hidden private members.

(I know that everybody reading this — except me — is much too smart to write a stupid class like this. It's just for demonstration purposes.)

Right now, the only way to test this class is to touch the file system twice — once to read in a test log file, and another time to check the results. In order to unit test private member functions, and check the state of private member variables (more on these below), you've got to resort to some sort of hackery, such as the infamous #ifndef hack:

Yes, there are other ways, but they all require a little too much intimacy with the test code for my taste.

Private methods and member variables are a code smell

Having lots of private methods and members often means that you've got another class (or two) dying to break free and live on its own. In the pathological LogParser example above, we really have three functions: we read and tokenize a log file, parse the tokens, then write our results to another file.

Having those private methods is a big hint that this functionality doesn't really belong on our LogParser class.

How about if we decompose this into three classes:

Here, we've got three much more focused classes, with much tighter responsibilities. This code is more reusable — it would be fairly easy to imagine taking that LogTokenizer and applying it in other situations, for example.

Note that the encapsulation is now better, if anything. Users of our LogParser class still don't have to worry about what's under the hood — and now they won't even be distracted by as many private member declarations when they browse the header file.

It will also be a lot easier to configure our LogParser to take different input and output sources. As one example, we could change LogParser to take a (smart) pointer to a LogTokenizer instance instead of an input filename, and then configure it with different LogTokenizer subclasses — including a fake tokenizer that doesn't touch the file system for testing purposes.

If I were to continue to refactor this code, I would expect to end up with almost everything public.

State is evil

Functional programming teaches that state (in the form of member variables) is evil, because it makes your code more complex and harder to test. No, C++ is not a functional programming language, nor is Java, nor C#, nor Python for that matter. But I think the functional programming style can teach us a lot about good programming in these languages as well.

I therefore try to avoid using member variables (which for C++, will probably be private for reasons touched on here). I generally consider it a problem to have more than about two of them in any given class.

The short answer is, it convinced me to start using the boost libraries (and the Loki library). I'd seen these libraries before, and thought that they looked pretty neat, but that most of them looked too esoteric to be really practical.

But that was really a failure of imagination. Learning Python taught me the value of programming at a higher level. Things like using boost::signals to break up dependencies; boost::bind and boost::function to use functions as first-class objects; boost::foreach to separate iteration from the algorithm; boost::any for generic data types; and much more.

Kind of ironically, Python also taught me the value of using a functional programming style in C++. I say ironically because Python isn't a functional language (although it supports a functional programming style). It was reading the book Text Processing in Python (David Mertz) that showed me the value of this style; then as I got more into TDD, the value of this style became clearer.

Today, I couldn't imagine not programming at a higher level in C++. My C++ code is now shorter, easier to understand, and has fewer bugs and platform dependencies. But I might have never moved to this new level if Python hadn't shown me the way.

A class represents a bundle of data and behavior. A classic example is a BankAccount class, which maintains a "balance" state and various methods for manipulating and querying the balance.

This is a great concept. It lets us think about our programs at a higher level.

The problem with classes is side effects. It's a lot harder to test a function when it depends on internal state — and that's what the "data" part of our data and behavior bundle is. It's harder still when calling the function may twiddle this internal state, which will in turn affect subsequent behavior.

It's easiest to test a function when a given input is guaranteed to produce the same output, no matter when or how many times it's called (i.e. a "pure function"). This yields code that's more reliable, more testable, and easier to reuse.

I don't think it's wise to completely forgo classes though, at least in languages like C++ and Python. They make large-scale development a lot easier. But these languages do give us tools for organizing code that the "classes-only" one-trick-pony languages don't — namespaces in the case of C++, and modules in the case of Python. So we don't have to resort to classes merely to organize related functionality.

Python also gives us functions as first-class objects (and boost does this for us in C++), eliminating another need to use classes: we can pass around functions rather than "command objects". A command object is fine when the command needs to retain state (e.g. for implementing undo/redo), but when a simple function will suffice, use a function.

When I'm developing new functionality, I try to use plain pure functions as much as possible, only using classes when I actually need to wrap state. C++ and Python give us this power, because they don't put us in the class straitjacket.