Form API: the next generation

I hate Drupal's form API. I love it, but I hate it as well. At times, it allows you to do amazing things with your forms, all from the safe surroundings of PHP, which you have grown to hate and love just as much. At other times you sit behind your desk, cursing and abusing your keyboard, because the one property you really need isn't available for the element you are using, or because form.inc is such an incomprehensible pile of junk.

Within the Drupal community, the usual response when someone criticises how Drupal works–or how it doesn't– is the infamous "File a patch!", which people hate and love as well (developers love it, users hate it). I decided to ignore this comment. Not because I'm a developer-hating user (I'm a user-hating developer). Not because I'm an arrogant prick (I am, but just not now), but because a single patch just wouldn't do.

I made a first stab at what I hope will become Drupal 8's new form API. It uses OOP, has better documentation and it's far more flexible. Get it now and tell me why it sucks, and how it should work instead. Then realise that you already know my answer...