Most applications you use daily are single threaded.  For those unfamiliar with threading, I liken a thread to a single train of thought, and a processing core to a single brain.  A single processing core (”brain”) can only work through a single thread (”train of thought”) at a time.

In a world of single threaded applications, multicore architectures are largely pointless.  If a single threaded application can only use a single core at a time, what use is it to have two, four, or however many cores?  Oh sure, if you have two intensely processing-intensive applications, and a dual core machine, you can run the two side by side at near* full steam, but how often does that happen?

We software developers need to be writing multithreaded applications, and taking advantage of the huge opportunity we have.  It doesn’t seem unreasonable to suggest that the chipmakers are moving slowly in the direction of boasting chips with many, albeit individually slower, cores.  I would not be surprised to see a 16 core CPU hit the market by the time I graduate college.  Now, balancing the number of cores with clock speeds will be an ongoing battle, I think, unless some breakthrough is made, allowing us to sidestep the current thermodynamic hurdles for a while.  It’s not uncommon for a GPU to have hundreds of smaller cores.  Look at the NVIDIA’S CUDA technology.

This is no longer a chicken and egg problem.  The chipmakers have built us - are building us - multicore processors, and we should learn to use them properly before someone decides there’s no substantial market for the technology and bails on the idea - there are no winners in that scenario.

* The most common design pattern for a multicore processor is to duplicate the Registers, Control Unit, and Arithmetic Logic Unit, but for the sister cores to share the same L2 cache and bus interface.  And of course, from there on out, the rest of the machine is also (stretching the logic just a bit farther) shared by each core.  So, while you may have 200% the raw processing power, your other system resources will become bottlenecks, thereby cutting back on the overall gain.  Especially important to avoid overcrowding in this situation is the bandwidth of the main system bus.

How could someone manage that?!  You’d think that someone literally would have to have been trying their hardest to screw up so royally, in order to achieve such mind-bogglingly astounding levels of failure.  It’s really impressive.

As far as web development goes, one time I saw black text on a yellow background, alternating (rather epileptically - you know what I mean) with white text on a black background.  That is how NOT to style your webpresence, whatever it is for.  Period.

More recently, though, I noted in a flash application, that the developers had chosen to grey out and center the text as it was entered into two input elements.  It was highly unnecessary, very unbalancing, and, more dangerously than the rest for the maintainers of the site, very distracting.  I very honestly debated entering my email address and would-be password.  I’m not sure what made me hesitate, but something about the fact that, in a form that was not centered, on a page in which nothing else was centered.  The text I was typing into these input elements, inexplicably, was centered though.  Someone got carried away.  And someone else OK’d it - that’s almost scarier.

Maybe I’m way off base on this one.  Maybe it was really not a big deal.  But, personally, this went down in my book of what NOT to do.

The centered input-elements aside.  In my own travels - of life, of the internet, on the road - a single quote has had an enormous impact on me.  I do not know whom to give credit for it’s astounding wisdom.  An intelligent man learns from his mistakes.  He is wise who learns also from the mistakes of others. When you see something so flagrantly ill-executed that it makes you instantly piteous and amazed all at once, don’t just wave it off and say “well that was dumb.”  Do yourself a favor - take a minute to breathe in the finer, more subtle details of the mishap, and learn not to do the same.

I can’t get enough of Gmail.  It rules.

The conversation-based (as opposed to singular message-based) interface approach is a quite simple, yet ingenious tweak that really gives the web app a nice flow.  And, of course, it’s Google technology, so with Gmail, everything is search-able, and you never have to delete anything.  Also, the spam filter has never failed me once.

What could be better than my Gmail address having an interface of this caliber?  Why, having ALL of my email addresses use a similar interface.  And that’s just what Gmail lets you do.  You can use your standard Gmail account as a [POP or IMAP] client for up to five (count ‘em, FIVE) additional addresses.

Now, I’ve been using Gmail like this for about six months, and I have to say I’ve been completely satisfied in every way.  Except one.  Every once in a while, I’ll get someone ask me why my name, on mail I’ve sent, appears “On Behalf of Chris Tonkinson.”

Gmail acts as does any other POP or IMAP client - so why should my outgoing mail be thus disorganized and unappealing? It turns out that when you send mail from a different address through your Gmail interface, Google automatically adds your Gmail account to the “sender” field to avoid it looking like spam.  And, in some versions of Microsoft Outlook, this can lead to the interface declaring that you are sending mail on your own behalf.

Perhaps you view this as proper behavior.  Perhaps not.  Either way, it seems annoying that anyone using Outlook should be encumbered by this extra verbiage.

Let’s unpack this.  In each instance you’re moving away from a single, absolute integer, to an easier-on-the-eyes formatted string.  But why stop there?  That’s where “fuzzy time” functions come into play.  They take a given time value (timestamp, datetime, or something to that effect) and, with some very simple logic… lay it out in a much easier-to-swallow way, such as “today at 8:16am,” “yesterday around 1:30pm,” and “about two weeks ago.”  A buddy of mine used to have a fuzzy time widget for his (Fedora) desktop that ran the gambit, abstracting time as specifically as “early morning” to as generally as “early winter.”  Perhaps that’s going too far, perhaps not.  You be the judge - I thought it was pretty funny.

Back to the topic at hand.  I’ve always admired Facebook’s use of fuzzy time for status updates.

At certain times of day and night (and certain levels of non-sobriety) your users can’t even parse some of the nicest date() output.  So, I went ahead and wrote a very simple PHP function to take things just one level higher up the ole’ abstraction ladder. (Note that line 2 only existed in my example script to save me typing.)

function fuzzy_time( $time ) {
  echo "\"$time\" is: ";
  if ( ( $time = strtotime( $time ) ) == false ) {
    return 'an unknown time';
  }
  define( 'NOW',        time() );
  define( 'ONE_MINUTE', 60 );
  define( 'ONE_HOUR',   3600 );
  define( 'ONE_DAY',    86400 );
  define( 'ONE_WEEK',   ONE_DAY*7 );
  define( 'ONE_MONTH',  ONE_WEEK*4 );
  define( 'ONE_YEAR',   ONE_MONTH*12 );
 
  // sod = start of day :)
  $sod = mktime( 0, 0, 0, date( 'm', $time ), date( 'd', $time ), date( 'Y', $time ) );
  $sod_now = mktime( 0, 0, 0, date( 'm', NOW ), date( 'd', NOW ), date( 'Y', NOW ) );
 
  // used to convert numbers to strings
  $convert = array( 1 => 'one', 2 => 'two', 3 => 'three', 4 => 'four', 5 => 'five', 6 => 'six', 7 => 'seven', 8 => 'eight', 9 => 'nine', 10 => 'ten', 11 => 'eleven' );
 
  // today
  if ( $sod_now == $sod ) {
    if ( $time > NOW-(ONE_MINUTE*3) ) {
      return 'just a moment ago';
    } else if ( $time > NOW-(ONE_MINUTE*7) ) {
      return 'a few minutes ago';
    } else if ( $time > NOW-(ONE_HOUR) ) {
      return 'less than an hour ago';
    }
    return 'today at ' . date( 'g:ia', $time );
  }
 
  // yesterday
  if ( ($sod_now-$sod) < = ONE_DAY ) {
    if ( date( 'i', $time ) > (ONE_MINUTE+30) ) {
      $time += ONE_HOUR/2;
    }
    return 'yesterday around ' . date( 'ga', $time );
  }
 
  // within the last 5 days
  if ( ($sod_now-$sod) < = (ONE_DAY*5) ) {
    $str = date( 'l', $time );
    $hour = date( 'G', $time );
    if ( $hour < 12 ) {
      $str .= ' morning';
    } else if ( $hour < 17 ) {
      $str .= ' afternoon';
    } else if ( $hour < 20 ) {
      $str .= ' evening';
    } else {
      $str .= ' night';
    }
    return $str;
  }
 
  // number of weeks (between 1 and 3)...
  if ( ($sod_now-$sod) < (ONE_WEEK*3.5) ) {
    if ( ($sod_now-$sod) < (ONE_WEEK*1.5) ) {
      return 'about a week ago';
    } else if ( ($sod_now-$sod) < (ONE_DAY*2.5) ) {
      return 'about two weeks ago';
    } else {
      return 'about three weeks ago';
    }
  }
 
  // number of months (between 1 and 11)...
  if ( ($sod_now-$sod) < (ONE_MONTH*11.5) ) {
    for ( $i = (ONE_WEEK*3.5), $m=0; $i < ONE_YEAR; $i += ONE_MONTH, $m++ ) {
      if ( ($sod_now-$sod) <= $i ) {
        return 'about ' . $convert[$m] . ' month' . (($m>1)?'s':'') . ' ago';
      }
    }
  }
 
  // number of years...
  for ( $i = (ONE_MONTH*11.5), $y=0; $i < (ONE_YEAR*10); $i += ONE_YEAR, $y++ ) {
    if ( ($sod_now-$sod) <= $i ) {
      return 'about ' . $convert[$y] . ' year' . (($y>1)?'s':'') . ' ago';
    }
  }
 
  // more than ten years...
  return 'more than ten years ago';
}

The original base-function I used was one that I found on PHPClasses by a fellow named Andrew Collington.  The code was in a class method for getting fuzzy file times.  I took that code, broke it out into a function, and massaged the heck out of it.  The function takes as it’s first parameter any value accepted by the PHP function  strtotime().  I chose that because of it’s impressive flexibility.  The function I ended up with only goes back to a ten-year period.  I figure, if I ever write anything that has records older than that, I can update it pretty easily.  Here’s sample output for all of the different intervals the function currently supports:


"now" is: just a moment ago
"-5 minutes" is: a few minutes ago
"-30 minutes" is: less than an hour ago
"-24 hours" is: yesterday around 10am
"-48 hours" is: Saturday morning
"-90 hours" is: Thursday afternoon
"-1 week" is: about a week ago
"-2 weeks" is: about three weeks ago
"-3 weeks" is: about three weeks ago
"-4 weeks" is: about one month ago
"-5 weeks" is: about one month ago
"-3 months" is: about three months ago
"-9 months" is: about nine months ago
"-13 months" is: about one year ago
"-76 months" is: about six years ago
"-9 years" is: about nine years ago
"-26 years" is: more than ten years ago


I was suprised at how much character and youth it gave the site.  Thanks Andrew and Facebook!

I like the idea of web development abstractions.  That’s what CakePHP, symfony, and Rails all are, at a very high level.  They are systems which take care of lower-level grunt work for you, and free up your time to focus on site/application design, rather than the nitty gritty technical details of the actual programming itself.  All basically serve to answer the same cry: I don’t want to write the same code more than once.  For example, header logic that checks to see if the user is logged in, footer markup that displays links at the bottom of the page, left hand navigation, etc.  You place the code for these in certain places, and then you include them where you need them.

Taking it a step further, many of these tools can actually automatically handle including the code for you - provided you put it in the right places, name it the right name, use it in the right fashion, and only need it in certain circumstances.  Many of these frameworks will actually write code for you, if you take the time to learn their system.

Now, don’t get me wrong, there is absolutely nothing wrong with learning one of these systems, and then leveraging it to quickly churn out product.  However, I take issue with them for a single reason.  Say I commit hours, weeks, whatever, to learning Rails.  To really learning Rails, and being beyond proficient with it.  And then I spend the time to use it for several sites.  What happens to the first site where I want to step outside of the Rails paradigm?  Do something that it doesn’t support?  Do something that goes against it’s main function?

It breaks, or you break. Either you have to go then into the Rails core code, and start hacking it up (making upgrading to newer versions highly time-consuming, if not impossible in some cases), or you have to break down, and give up your dream (or find a compromise to make it happen).  All of these solutions are, to me, a bit unsavory.

What would really be nice, is a system that let you do what you do, but didn’t tell you how to go about it.  Offered you a set of tools that made you more productive, but didn’t get in your way when you wanted to go and do something non-standard.  That’s where Webstraction comes into play.  Webstraction provides standard methodologies for building web pages and accessing common code.  It is an abstraction in that, many times, the logical flow of page creation depends merely upon the existence or absence of a given file or directory.  It provides a really smooth interface for having the system automatically grab all necessary php, css, and javascript files for you.  Webstraction also has special handlers for Ajax requests.  And, most currently, I’m in the process of redeveloping it to support plug-ins (which seem, on today’s web, to be an expectation (Just look at the communities around Firefox, jQuery, and Wordpress, for instance).

I’ve submitted the project to SourceForge with a GNU/GPL license, and a recent version is available for download there, however I’ve not yet completed the documentation site, nor have I migrated the Subversion repository.  More updates to follow.

I’ve been getting pretty heavily into web development lately.  Wrote my own web development abstraction system (I cringe to call it a “framework” because frameworks, by definition, are restrictive, and my goal here was to do as much heavy lifting for the web developer as I could, without stepping on their toes at any point), and more recently, wrote a jQuery plugin for myself called Superedit.  I’ve really been loving jQuery.  Really loving it.  I would recommend it very highly if you’re looking to add any javascript to your site; jQuery makes web development a real pleasure.

As all of my project start, I got sidetracked.  While writing a site for the Honors Program here at my school, I decided that I’d like to make all “edit” functionality on the site happen via an edit-in-place system.

Take a user account page for example.  Say you want to change your contact email address.  The form might look like so:

And when you click on the span, I use JavaScript to turn it into an input like so:

You edit the content:

And then, on JavaScript’s blur() or change() events, the content is saved via callback, and the input is turned back into a span:

Now, personally, I think this is one of the greatest toys Ajax has given us so far.  The ability to edit (and validate) form input without having to reload entire pages for a single element to change.  Of course, the first [working] iteration of this system spanned two disjoint JavaScript files, a php header, a php function file, and then more configuration in the markup itself.  Now I’ve got it down into two plain jQuery methods.  To initialize the element for display:

$( 'selector' ).superbox( 'initial value', callback, { options } );

And to initialize the element for editing:

$( 'selector' ).superinput( 'initial value', callback, { options } );

And the plugin handles the rest.  The only tricky part has been getting the callback to behave itself, so I’m working on getting that stable.  jQuery plugin generation is actually a pretty pleasant process.  A good primer can be found directly from jQuery’s documentation, and once you’ve gone through that, an excellent practical demonstration can be found here.

I’ll probably be posting again soon on Superedit when I get it stable and formally add it to the jQuery Plugin list.  If you want to add hover event handlers, use collapsible containers, Ajax, browser-dependent scripting, or, like me, you want to extend the already sprawling library and bend your XHTML to your will, javascript has never been easier.

… I think I should get paid for advertising.

You’ve heard all about the big three: Windows, Mac, Linux.  I know the topic has been beaten to death and back again, but I feel compelled to inject a bit of objective commentary to the fray.  First, a history lesson, I should think.  In order of popularity - that is to say, market share at the time of posting.

In 1980, an employee of Seattle Computer Products wrote a disk operating system called 86-DOS (also known as QDOS) for IBM Personal Computers using the Intel 8086.  Microsoft Corp. licensed the software, fiddled with it, and sold it as MS-DOS (”Microsoft Disk Operating System”) in 1981.  MS-DOS quickly gained popularity and market share.  In 1985, Microsoft released Windows version 1.0.  Windows continued over three major revisions until 1995.  None of which were true graphical operating systems in their own right; rather they were simply graphic shells placed over top of MS-DOS.  Windows 95, released in 1995 (surprised?) was the first true GUI OS from Microsoft.  It included a command line reminiscent (read: taken directly from) MS-DOS, however this was merely the shadow of DOS, and not a window into the heart of the operating system.  Even through to Windows Vista, traces of DOS can still be found.

Apple Incorporated released the Macintosh 128k in early 1984.  This system was largely a success for Apple.  The Macintosh 128k featured a mouse and keyboard to support a complete graphical user interface, which had not been done successfully before (an attempt called the Apple Lisa failed fairly quickly due to high costs and limited software availability).  A few attempts later, Apple released the Macintosh Plus in 1986 which was, arguably, one of it’s more popular systems.  System 7 was the first Mac to natively (and fully) support 32-bit addressing.  Via many significant patches and retrofitting, Mac OS made it’s way up to version 9.2.2, however the system quickly became dated, and in early 2001, Apple released Mac OS X - entirely rewritten using the Unix variant (a hybrid of Nextstep and FreeBSD) called Darwin.

In the 1960’s, MIT, Bell Labs, and GE jointly worked on an experimental operating system called Multics.  The project wasn’t particularly a hit, and eventually was dropped.  However, one of it’s developers, Ken Thompson, led a team in writing a novel operating system for the PDP-7 in assembly language called Unics (yes, a play on the name Multics), which was to be a secure, efficient, time-sharing (read: multiuser) system.  Unics was later renamed Unix.  Between 1969 and 1973, the C programming language had been written by Dennis Richie et. al., and in 1973, Unix was rewritten in C.  In 1984, Richard Stallman announced the GNU free software project with the goal of organizing a unix-compatible operating system entirely comprised of free software.  Many things went well for the GNU Project.  Their microkernel, called Hurd, was not one of them.  However, in 1991, Linus Torvalds generated the monolithic Linux kernel, which was compatible with GNU software.  This springboard gave enormous popularity to both projects and arose to what is now called the “Linux” operating system, although it is more properly titled “GNU/Linux.”  Many, many, many GNU/Linux derivations exist today.

Now that we’re (roughly) on the same page, which one is best?  The answer is simple: they all suck.  If you’re a graphic designer, Linux will put you through torture and a half.  Once you get done with all those pesky configurations files, manage to get your devices working properly, and swallow the fact that there’s no 1-800 number in case your machine crashes, you’ll realize that Adobe Photoshop CS3 is not available for you.  If you’re a gamer, you scoff at Mac.  It’s useless.  I can’t play Team Fortress 2?  The mouse only has one button!  Where’s the registry?  And certainly, if you’re a hard-core dev, you can’t stand all of Windows’ quirks.  Memory leak galore, reboots after every five minutes, security measures consume the first hour of your morning routine…. And Mac?  You can’t even tool around in certain system directories!

My favorite argument is the classic Windows guy vs. Mac guy.  Let me explain what I mean.

Windows guy: Mac is too simple - there’s not even a right click!

Mac guy: Windows is too confusing!  And what the heck is a right click?

Windows guy: There’s no control key!

Mac guy: Use the apple key, dummy!

Windows guy: I just want to defrag my computer now and then, alright?

Mac guy: I just want my computer to work!

[The Linux guy walks in, and the other two roll their eyes.]

Mac guy: Oh jeez….

Windows guy: Not HIM again…

Linux guy: Pffft…. Noobs.

You’ve heard it - you know you have.  You’ve said it yourself, even.  What is it, I wonder, about people and their obsession over their preferred operating system?

I haven’t figured it out quite yet.  But let me be perfectly clear.  If an operating system does what you need it to do, how you need to do it, and within reasonable limits of timeliness, then it’s the best system for you.  And if your buddy has different needs, a different system might just be the best for him.  Even if (heaven forbid) it’s from a competing vendor. One of my personal pet peeves are those computer users who religiously claim that their choice of operating system is simply the only viable solution, and anyone who claims any differently is a heretic.

I just like to keep in mind a simple analogy, whenever the topic arises.  A Caravan would not be the optimal vehicle for a 17 year old student to drive back and forth to high school every day, while a Neon is certainly not the most sensical choice in transportation for a mother of 4.  (Note, however, that both are produced by Dodge because, of course, Mopar is always the best manufacturer…)

That having been said, for those unfamiliar with it, let me explain. Version control software is a client-server application which tracks changes in files over time. That’s it. Pretty dull, huh? It has it’s uses. When you want to start a new project, you create what’s known as a “repository” for it under the version control system. The repository keeps track of all the files you’re dealing with. If you delete a file from your project, you tell the repository that you deleted it. If you add a file to your project, you tell it that you added a file. And when you change files, you tell it which ones you changed. And that’s really all there is to it.

If this seems unnecessary, that’s understandable. It did to me at first. But there are numerous advantages to be gleaned from using version control software, such as CVS, or Subversion which is what I use. Ever have one of those dismal “oops” moments? The kind when you’re crawling around on the command line (am I the only one who still uses the CLI?) and you accidentally delete a file? Or you accidentally overwrite the wrong file? Well, them’s the breaks, I’m afraid. Unix isn’t shy. You delete a file, it’s gone. Unless you’re sitting on a nice desktop like Gnome or KDE, which has built in recycle-bin functionality, then that file is history.

Or is it?

If you’ve been using version control religiously - which I submit as the only way to use it - then all you have to do is open up your version control client application (I recommend TortoiseSVN if you’re on Windows, and RapidSVN if you’re running Linux) and revert the dirty deed from the repository. It’s that simple. There’s always the wonderful case when you find a bit of code, and you don’t know when or why it was added, and you remove it, only to find out days later it broke another section of the application. Version control will let you bring up ANY previous version of a file that you’ve committed to the repo (that’s short for repository), at the push of a button. And with a nice file comparison tool, you can easily see what you changed, and where.

A good version control client will also allow you to merge files together. Say you’re working on lines 1-40 of a file, and I’m working on lines 41-100. Well modern version control systems were built with teams in mind. You commit your changes, and I’ll commit my changes. If our code changes don’t affect one another, then the two will be accepted by the repo without complaint. If they do conflict, however, you’ll be able to see what’s different where, and easily rectify the disagreement.

If you aren’t using version control for every project, then you’re doing yourself a disservice.

As a note, I like Subversion because of it’s ease of use. Also, Tigris (who maintains Subversion) puts out both the Windows and Linux clients I mentioned, TortoiseSVN and RapidSVN, respectively. So it’s all packaged by the same great folks. And those file comparison tools I was blathering about? TortoiseSVN has one built right in. For Linux I can recommend Meld. There’s a small learning curve, just in getting used to how these systems work, and learning to discipline yourself into using them properly, but once you get it - I hate to use cliches - it really is one thing you’ll wonder just how you got by without.

For those who don’t have a server of their own, or don’t feel like tooling around with daemon services, there are free online services such as the wonderful Assembla which provide a Subversion server to you, wherever you are. All you need is a network connection.

Today, we look at automatic documentation software. What’s that… a program that writes your comments for you? Hardly. But what documentation generation software WILL do, is take the comments you write in your code, and coerce them into a more user-friendly format, usually within an html environment. And, if you pick the right software, it can do a whole lot more for you.

A lot of developers tend to think of documentation simply as the comments throughout their code.

/* This is a C-style
* block
*comment
*/
# This is a shell script comment
// This is a PHP-style comment

And of course there are more. This is nice for the casual developer, personal projects, and the like. But for really large projects, for hard-core open source stuff, or for professional software, there’s something missing here. What if you’re on a team, and you want your team to know how to use an API you wrote, without worrying them with the specifics of it’s implementation? What if you just want a professional looking interface to your latest and greatest API? Perhaps you’d just like something to throw online to prove to others “Hey, I am actually working on this” without blindly tossing source code onto the interwebs. This is where documentation generation comes into play.

I’ve got experience with Doxygen. Great open source project. For Doxygen (and it’s the same with others, such as phpDocumenter and Javadoc), all you need to do is format your comments the proper way. For a block-style comment, use the form:

/** This is a bloc comment. */

or

/** This is a
* block comment.
*/

Inline comments (C++-style) go like this…

/// This is a line comment, and applies to the code below it.
<This is some code>

And this

<This is some code> ///< This comment applies to the code preceding it.

That’s it. That’s all you have to do, and Doxygen will create documentation for you in a slew of forms, including html, xml, latex, rtf, postscript, pdf, and even Unix man page format. Here’s an example of Doxygen’s output. Note that all the developers of that code had to do, was to follow the commenting convention set by Doxygen. Doxygen was responsible for chewing through all of the code, writing the HTML, styles, diagrams, links, lists, tabs… everything!

Doxygen supports “C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D” according to it’s website. Now like I said at the beginning, which documentation generator you use is your choice, but I’d HIGHLY recommend trying one/some out then actually using it/them. Doxygen is also capable (alongside graphviz’s dot tool) of creating images that depict call graphs, dependency trees, and the like.

I’m pretty sure that anyone who has (successfully) used an API at some point will tell you that they are wonderful. What I’m also guessing, from my admittedly limited experience, however, is that a lot of them will also tell you, if they’re honest, that APIs can be clumsy. Why is that? From the C/C++ perspective, the answer is dreadfully clear to me. Many of the most basic and useful APIs are written in C. Which means the large portion of them were written using a procedural paradigm.

You’re required to create a resource handle object (be it a pointer to some struct or class as in the MySQL and cURL C APIs, or maybe just a plain old int, as is the case for using POSIX threads), and then call a barrage of functions (passing the handle as a parameter each time) to manipulate it. Straightforward enough for any reasonable person, I’d estimate. Arbitrarily using cURL as the example, we typically see something like the following…

CURL* handle;
curl_easy_setopt( handle, CURLOPT_ERRORBUFFER, _error );
curl_easy_setopt( handle, CURLOPT_FAILONERROR, true );
curl_easy_setopt( handle, CURLOPT_FOLLOWLOCATION, true );
curl_easy_setopt( handle, CURLOPT_HEADER, false );
curl_easy_setopt( handle, CURLOPT_NOSIGNAL, 1 );
curl_easy_setopt( handle, CURLOPT_AUTOREFERER, 1 );
curl_easy_setopt( handle, CURLOPT_SSL_VERIFYPEER, 0 );
curl_easy_setopt( handle, CURLOPT_NOPROGRESS, true );
curl_easy_setopt( handle, CURLOPT_CONNECTTIMEOUT, timeout );
curl_easy_setopt( handle, CURLOPT_MAXREDIRS, 5 );
curl_easy_setopt( handle, CURLOPT_TIMEOUT, wait );
curl_easy_setopt( handle, CURLOPT_USERAGENT, agent.c_str() );
curl_easy_setopt( handle, CURLOPT_VERBOSE, false );
curl_easy_perform( handle );


Not too bad, a few lines for the ability to browse the web. Decent enough, says me. Especially when the alternative (without the API that is) would be to use the system() function to pass a string like the following to the OS.
curl -f -v –connect-timeout 30 –data-ascii –url http://www.somesite.org/index.html

Portability? What’s that? Worse yet, you could use libcurl nude. Yikes. And by the way, that string isn’t NEAR complete, if we’re dedicated to all of the customizations represented in the sample code. I don’t even want to think about that. So… looking at it this way, an API couldn’t get better. But seriously. What kind of self-respecting programmer doesn’t try, at least once in a while, to fix what isn’t broken? Come on… admit it. You’ve done it. You did it once a long time ago and learned your lesson. And then a situation, much like the above, arises and you said to yourself “Robert - ” since that may in fact be how you address yourself - “Robert, this works… but I can do better.” It’s natural. Some of these APIs - as much functionality as they offer, and as wonderful as they are, just don’t cut it sometimes. The libcurl C API, for instance, requires you to implement two callbacks, which are responsible for some very low level memory allocations and pointer dereferences. Stuff that would make one of this new generation of upcoming greenhorn developers (who know naught but their fancy, highly abstracted, memory managed interpreters) run home and cry in the fetal position. Jeez - I didn’t even want to do it, and I’m a fan of the low level stuff. So who wants to do that every time you write an application that needs to rip a web page? Who wants to do it for a SINGLE app that needs to rip just one page?

Not me.

Probably not you.

And, if you’re anything like me, you despise re-writing code. One of the biggest problems with this type of code is the fact that it flies in the face of all that fancy object oriented paradigm you’re expected to exalt. This is my idea. For about a year now I’ve been doing this, and it’s worked wonderfully. Before you use an API, think about it. Then, take the hour to learn the API. Test it a few times. Be a little crazy. Get comfortable with it. And then take a second hour… maybe two… and write a well formed, object oriented wrapper class for the API. Commit this class to your favorite version control system (I prefer Subversion). Then take the time to debug it. Let’s face it. Sometimes, you just have to sidetrack from your project, and I think this is a perfectly legitimate cause.

Let’s examine the situation. You’ve now got a properly written class wrapping an API at your disposal. Granted, some APIs are quite large, so this may be no trivial undertaking. But, get the bare bones working first, and then add on as you need/want to - as with any development project. Instead of all that code *up there* (that doesn’t include stuff like those nasty callbacks, which, using my method, you’d only have to write once) all you need is something like this:

Curl curl;
curl.setUrl( "http://some.place.dot.com/index/page.html" );
curl.exec();


Oh, and the html you grabbed can be accessed via curl.getResult(). Isn’t that a lot better? Granted, you’re now probably half a day “off course.” But guess what? You were going to have to learn and get used to the API anyway. You were going to have to hack your way around it’s quirks anyway. You were going to have to write 90% of that code anyway in your actual application. And, the real reward, the next time you have to use cURL in an application, it’s as easy as copying the wrapper class files into your project directory and using them.

Personally, I’ve got wrappers written for cURL, MySQL, PCRE (Didn’t do much for this one, just re-packaged libpcrecpp from teh kind folks over at Google), Pthread, and a C++ implementation of the MD5 algorithm I found online. I’ve also got a wrapper on some common time functions in a class called “Timer.” And they’re all committed to a single version control project. When I need to add functionality, I go back, update this project with the proper code, and then, once all is copesetic, copy the updated files to whatever project needed the wrapper.

Now, of course, the wrapper can’t do EVERYTHING for you. Some APIs, like cURL and Pthread, require callbacks and whatnot. Of course, you deal with these case-by-case as appropriate for your situation. But I’ve found that these wrappers can save a LOT of time in both the writing and debugging phases. Also, they pay for themselves the first time you use them, if for no other reason than the fact that they keep your project code looking neat and object oriented, as it should be. Develop them generically, and you can use the same wrappers for multiple projects (of course adapting them as needed, when needed).