`registerMatcher` sample usage as of Feb 10, 2014.

CruiserSpec.m

#import "Kiwi.h"
#import "Cruiser.h"

registerMatcher(haveFighters)    // From what I understand, the `registerMatcher` macro
registerMatcher(haveNoFighters)  // is simply a trick to enable code completion in Xcode.
                                 // Using this twice causes a warning for duplicate category
                                 // definitions.

SPEC_BEGIN(KWUserDefinedMatcherFunctionalTest)

defineMatcher(@"haveFighters", ^(KWUserDefinedMatcherBuilder *builder) {  // Matchers are customized by calling methods on builder
    [builder match:^BOOL(id subject) {                    // `match:` takes a block which
        if (![subject isKindOfClass:[Cruiser class]]) {   // returns NO for match failure,
            return NO;                                    // YES otherwise
        }
        Cruiser *cruiser = subject;
        return cruiser.fighters.count > 0;
    }];
    [builder failureMessageForShould:^(id subject) { // You can also specify custom failure messages.
        return [NSString stringWithFormat:@"%@ should have fighters", subject];
    }];
});

defineMatcher(@"haveNoFighters", ^(KWUserDefinedMatcherBuilder *builder) {
    [builder match:^BOOL(id subject) {
        if (![subject isKindOfClass:[Cruiser class]]) {
            return NO;
        }
        Cruiser *cruiser = subject;
        return cruiser.fighters.count == 0;
    }];
    [builder failureMessageForShould:^(id subject) {
        return [NSString stringWithFormat:@"%@ should have zero fighters", subject];
    }];
});

describe(@"Cruiser", ^{
    it(@"has fighters", ^{
        Cruiser *cruiser = [Cruiser new];    //
        [[cruiser shouldNot] haveFighters];  // LLVM warns of Memory leak here.
        [[cruiser should] haveNoFighters];   //
    });
});

SPEC_END

I have several problems with this:

1. LLVM memory warning occurs in it block "has fighters".
2. I feel like match: is a strange name for a method which takes a matcher block. A property might be nicer.
3. Is it possible to define matchers which take an argument?