Follow me as I poke Expecta with a stick to see how it works - it’s pretty cool.
It’s been a long time since my last post but I thought I’d get stuck into how something that appears simple actually works. That subject will be Expecta matchers. If you don’t know what Expecta is then you might want to nip over to the Github repo and skim the Readme then we can get stuck in.
Take the following example:
expect(2).to.equal(2);
This line looks so simple but it’s hiding a lot of clever techniques that may or may not be useful to keep within your own development bag of tricks.
Let’s break this apart and demystify what’s really going on.
##expect
expect() looks like a function call, so you may assume that there is a function declared somewhere called expect. Thankfully that is not the case or this blog post would be very boring - instead we find this defined as:
_EXP_expect is the actual function we was looking for.
At this point you may be wondering why did they bother with this odd chain of macro expansions. The logical reason would most likely be that expect(id actual) is an optional short hand syntax, which is only enabled by defining EXP_SHORTHAND before importing Expecta.h. Without this define you have to use the long hand EXP_expect(id actual) and this is what expands to _EXP_expect with all the additional arguments.
Go ahead and reread that last paragraph a few times if it didn’t sink in the first time.
In effect the define for expect saves you from having to type out
The _EXP_expect function simply creates a new instance of EXPExpect with all the arguments supplied. I’m not going to go over the EXPExpect class as I want to cover the single line of code at the top of this post.
Before we move on though it’s worth pointing out that Expecta is really cool as it does not require you to box your arguments. It’s the EXPObjectify function that does the work of making sure that if you pass in a primitive like int, float, double, etc then it will box it with an NSValue or NSNumber automatically for you.
##to
to looks simple enough - so why is this interesting? Well knowing that it is used like this to.equal... leads us to the conclusion that it returns an instance of something that responds to equal. Before following the link to look up the definition keep in mind that to is entirely optional and I could validly call expect(2).equal(2); - this should narrow down what to returns.
@property(nonatomic,readonly)EXPExpect*to;
Yup you may have guessed it to returns an instance of EXPExpect - not just any instance but the instance it was called on - check it out:
-(EXPExpect*)to{returnself;}
This is just a little sprinkling of syntactic sugar. It makes the expectation read better consider expect(2).to.equal(2) vs expect(2).equal(2).
##equal
By now you are probably thinking that the interesting stuff is over and equal will just be a property declared on EXPExpect. You may also come to the conclusion that the property will return a pointer to either a block or a function so that it can be invoked with parentheses and an argument equal(2). This is exactly what is happening - kind of…
If you search the EXPExpect class you will not find a property declaration but if you follow the declarationf of equal through you’ll land in EXPExpect+equal.h, which looks like this:
#import "Expecta.h"
EXPMatcherInterface(_equal,(idexpected));EXPMatcherInterface(equal,(idexpected));// to aid code completion#define equal(...) _equal(EXPObjectify((__VA_ARGS__)))
This is where we have to make sure our brain is really engaged and step up a gear. Take a breather and join me after the relaxing grey line…
In english this has declared a named category called _equalMatcher on the EXPExpect class. This category declares a single readonly property, which means that in the .m file we would expect to see a single method declared with the signature - (void(^)(id expected))_equal;
NB I showed the mapping of _equal as equal is only used for code completion and there is in fact never an implementation declared for - (void(^)(id expected))equal;
So being inquisitive we jump to the implementation to see how this method is defined and we find more #define magic.
EXPMatcherImplementationBegin(_equal,(idexpected)){match(^BOOL{if((actual==expected)||[actualisEqual:expected]){returnYES;}elseif([actualisKindOfClass:[NSNumberclass]]&&[expectedisKindOfClass:[NSNumberclass]]){if(EXPIsNumberFloat((NSNumber*)actual)||EXPIsNumberFloat((NSNumber*)expected)){return[(NSNumber*)actualfloatValue]==[(NSNumber*)expectedfloatValue];}}returnNO;});failureMessageForTo(^NSString*{return[NSStringstringWithFormat:@"expected: %@, got: %@",EXPDescribeObject(expected),EXPDescribeObject(actual)];});failureMessageForNotTo(^NSString*{return[NSStringstringWithFormat:@"expected: not %@, got: %@",EXPDescribeObject(expected),EXPDescribeObject(actual)];});}EXPMatcherImplementationEnd
When the two macros are expanded we end up with this (formatting mine):
If we didn’t want to use the macros (not advised at all - only shown for interest sake) then the implementation could remove the added complexity of setting up the DSL and end up with an implementation like this:
-(void(^)(idexpected))_equal{__blockidactual=self.actual;return[[^(idexpected){EXPBlockDefinedMatcher*matcher=[[EXPBlockDefinedMatcheralloc]init];matcher.matchBlock=^BOOL{if((actual==expected)||[actualisEqual:expected]){returnYES;}elseif([actualisKindOfClass:[NSNumberclass]]&&[expectedisKindOfClass:[NSNumberclass]]){if(EXPIsNumberFloat((NSNumber*)actual)||EXPIsNumberFloat((NSNumber*)expected)){return[(NSNumber*)actualfloatValue]==[(NSNumber*)expectedfloatValue];}}returnNO;};matcher.failureMessageForToBlock=^NSString*{return[NSStringstringWithFormat:@"expected: %@, got: %@",EXPDescribeObject(expected),EXPDescribeObject(actual)];};matcher.failureMessageForNotToBlock=^NSString*{return[NSStringstringWithFormat:@"expected: not %@, got: %@",EXPDescribeObject(expected),EXPDescribeObject(actual)];};[selfapplyMatcher:matcherto:&actual];}copy]autorelease];}
This version seems like an awful lot of error prone boiler plate code that a developer would have to write for each matcher. Keep in mind that there are ~25 matchers included with Expecta and you can define your own.
Let’s list the required steps for this implementation:
Configuring this instance’s properties with blocks for matchBlock (line 7), failureMessageForToBlock (line 18), and failureMessageForNotToBlock (line 22).
Ensures that [self applyMatcher:matcher to:&actual]; is executed at the end of the block that is declared and returned (line 3).
In this implementation there are only 3 steps so this must surely be better?
Nope:
In the original list of 5 steps only step 4 was exposed to the developer and the remaining steps were hidden behind macros.
In this implementation the developer has to know about all 3 steps.
This means that the developer has 2 extra steps to remember to do and to make matters worse they are wrapping (before + after) steps.
In the first listing the developer is literally just stating the test requirements, whereas in this version the developer has to know about matchers and how they need to be configured in addition to the test requirements.
So hopefully now I’ve pulled back the curtain a little the line
expect(2).to.equal(2);
won’t seem as mysterious.
##Wrapping up
Well that was a heavy post with a lot to understand and I do apologise if I got any of it wrong - I’m no Expecta expert. Reading code is great fun especially when you get that Eureka moment and you learn something new. The joy of a project like Expecta is that it is all unit tested so you can hack around and change things to test your assumptions - hit test and wait for your theory to be validated with a sea of red or green unit test results.
Storyboards can really speed up development but a problem I run into over and over again is working with identifiers that are set in the storyboard and referenced in code.
#Problem
Let’s take the example of making a segue:
You create a segue and then assign it an identifier in the storyboard… and that’s the problem. The identifier is defined in the storyboard, which leaves me with plenty of opportunities to mess up referencing the segue in code.
My normal strategy is to create a constants file that would have a constant with the value of each of these identifiers, which starts to look like the following (forgive the naming):
This works for me and I’m happy, but it seems like a lot of manual graft and can become tiresome to maintain especially in a young project with lots of development spikes. It’s also still very possible to make typos and mess up these declarations or for them to become out of sync with the storyboard.
#Automation
I got to thinking about this problem and two things stood out
I don’t like doing things manually and
I don’t like that it is so easy to misspell a constant when swapping between storyboard and code (yes I am aware copy and paste exists).
So I started tinkering and I’ve come up with a rough tool that I’ve cunningly named sbconstants.
My automation idea is that you add a build script that will extract constants from your storyboards and then dump them into a file.
Grab it with
sudo gem install sbconstants
My first effort has a UI like this (command line app)
% sbconstants -h
Usage: DESTINATION_FILE [options]
-p, --prefix=<prefix> Only match identifiers with <prefix>
-s, --source-dir=<source> Directory containing storyboards
-q, --queries=<queries> YAML file containing queries
-d, --dry-run Output to STDOUT
-v, --verbose Verbose output
To get this working on a project the sbconstantsgem needs to be installed to the system Ruby and then we need to call the executable from a build script. An example call would look like this
NB The argument is the destination file to dump the constants into - this needs to be added manually
Every time this project is built it will parse the storyboard files and pull out any constants and then dump them into PASStoryboardConstants.(h|m). This of course means that PASStoryboardConstants.(h|m) should not be edited by hand as it will just be clobbered any time we build.
The output of running this tool will look something like this:
PASStoryboardConstants.h
// Auto generated file - any changes will be lost#pragma mark - tableViewCell.reuseIdentifier
externNSString*constPSBAwesomeCell;#pragma mark - segue.identifier
externNSString*constPSBMasterToDetail;externNSString*constPSBMasterToSettings;
PASStoryboardConstants.m
// Auto generated file - any changes will be lost#import "PASStoryboardConstants.h"
#pragma mark - tableViewCell.reuseIdentifier
NSString*constPSBAwesomeCell=@"PSBAwesomeCell";#pragma mark - segue.identifier
NSString*constPSBMasterToDetail=@"PSBMasterToDetail";NSString*constPSBMasterToSettings=@"PSBMasterToSettings";
The constants are grouped by where they were found in the storyboard xml e.g. segue.identifier. This can really help give you some context about where/what/when and why a constant exists.
##More options
Options are fun and there are a few to play with - most of these options are really only any good for debugging.
###--prefix
-p, –prefix= Only match identifiers with
Using the prefix option you can specify that you only want to grab identifiers that start with a certain prefix, which is always nice.
If you don’t want to run the tool from the root of your app for some reason you can specify the source directory to start searching for storyboard files. The search is recursive using a glob something like <source-dir>/**/*.storyboard
###--dry-run
-d, –dry-run Output to STDOUT
If you just want to run the tool and not write the output to a file then this option will spit the result out to $stdout
###--verbose
-v, –verbose Verbose output
Perhaps you want a little more context about where your identifiers are being grabbed from for debugging purposes. Never fear just use the --verbose switch and get output similar to:
sample output
#pragma mark - viewController.storyboardIdentifier////info: MainStoryboard[line:43](viewController.storyboardIdentifier)//context: <viewControllerrestorationIdentifier="asd"storyboardIdentifier="FirstViewController"id="EPD-sv-vrF"sceneMemberID="viewController">//NSString*constFirstViewController=@"FirstViewController";
Chances are I’ve missed some identifiers to search for in the storyboard. You don’t want to wait for the gem to be updated or have to fork it and fix it. Using this option you can provide a YAML file that contains a description of what identifers to search for. The current one looks something like this (NB this is a great starting point for creating your own yaml):
This looks a little funky but it’s essentially groups of keys and values (both the key and the value can be an array). This actually gets expanded to looks for
I’m not sure if this tool will be of any use to anyone but for the projects I’ve been tinkering with it seems to work pretty well leaving me confident that my storyboard identifier’s will not go out of sync with how they are referenced in code.
If anyone does use this and they like it or they have any issues please report it to me so I can get it fixed up and improve my own workflow.
Blocks are a lot of fun and they can make some really slick API’s. It’s also worth noting that blocks also require a fair amount of overhead to get used to how they work and how to use them. I would consider myself fairly competent with blocks but this confidence can lead to potentially “clever code”. “Clever code” is sometimes hard to maintain depending on how clever you was feeling at the time of writing it.
In this post I intend to cover one such bit of “clever code” and how it could be implemented differently to compare and contrast the results.
##Using delegates
I’ll start by looking at the implementation I didn’t actually do and then step by step arrive at the solution I initially wrote. From here I can compare and contrast and see which solution I should have done.
The sequence of events looks something like this
So at this point we have a working solution and all is good.
The code to loop over the points looks something like this
View.m
for(inti=0;i<self.dataSource.numberOfPoints;i++){CGPointpoint=[self.dataSourcepointAtIndex:i];// convert point and build path}
Something about asking for the count and then iterating over it seems a little awkward to me, I’d much rather the thing that held this information (the model) kept it’s data a little closer to it’s chest and iterated over itself passing out the points. There are two options here
This creates an issue - for this to work I would have to call this enumerator in the View. I could simply bypass the Controller and pass the View a reference to the Model but I don’t like the sound of this. The more pressing issue is that the Model works in a different coordinate space to the View and the Controller is currently handling this conversion.
To get this to work I’ll need to restructure to look like this
This diagram actually looks simpler. There’s a couple of things to now note
There are new required methods that need to be called and in a specific order beginDrawing and commitDrawing
The path building now occurs over a series of method calls to View
Straight away I can see a way to remove the requirement to call beginDrawing and commitDrawing at this level by using a block that wraps this up in a tasty sandwich.
##Sandwich block
The sandwich block puts the interesting code that changes as the sandwich filler and the boilerplate as the bread, which will look like this:
Every object appears to be toeing the MVC line, although I see a method that probably doesn’t belong in the public API. The View now has the method -[View buildWithPoint:], which only makes sense in the context of drawing, it’s not clear by looking at the public interface what this method does or in what context to call it.
So here’s another opportunity to use a block, this final implementation brings us to the title of this post Blockception. We now end up with a block in a block which calls a block passed in by the first block.
The drawBlock essentially takes the functionality of the old -[View buildWithPoint:] and passes it straight where it is actually needed.
##Differences
###Delegate Implementation
The delegate implementation requires a fair amount more code to write. A @protocol needs to be introduced to allow the view to have a dataSource. There is also the methods on the controller that conform to this protocol and end up proxying them straight onto the Model and then slightly changing the result.
Looking at the initial sequence diagram there seems to be more back and forth of messages to achieve the same result than where we end up.
The Model is required to expose how many elements it has and then allow an external object to iterate over that in a way which is out of it’s control.
###Block Implementation
The block implementation has 2 of my favorite ways to use blocks, which are for enumeration and wrapping code.
The public interfaces for all the objects expose very little about themselves, which is always nice.
There are considerably more awkward carets and curly braces, which can be confusing.
##Conclusion
Looking back at both solutions the delegate technique can be easier to fully grasp and follow along. The block implementation completely failed my “can I explain how this is working to a colleague in one attempt” rule, but I feel the delegate setup would only fair slightly better.
The reason I originally implemented this using blocks over delegates was purely because I had the block enumeration on the Model and this was the only way I could think to make it all fit.
I do like how the block implementation hides away any gory details about the structures of the objects but the very fact that I’ve had to write a blog post about this probably means it’s too clever. I think the answer to “which is better?” is we’ll have to wait and see how the block implementation stands up over time.
