Lhunath

Clean up your configuration

2009-08-07T23:17:00.002+02:00

What we all want

When you're writing an application, whatever platform you're writing it for and whatever framework you're writing it in, you're going to want your users to be able to customize some of it. If that isn't the case with you, you likely write cron jobs all day long and you might as well stop reading.

Those configurations that our users provide us with need to be stored somehow. Users don't like setting their application up each time they want to use it. Different platforms have different ways of approaching this problem; but generally speaking the approaches are very application-specific and terribly verbose in code. Code verbosity sucks. It makes your code complex and opaque. Your code should be simple and transparent.

So, what we all really want is a simple, short and generic way of gathering, storing and accessing user configuration; preferably in a way that involves strong type safety of the actual data that each configuration property reflects.

What I present to you today is an Objective C approach of doing just that.

Persistence

The first obstacle that we need to considder is the persistence of our configuration data. Collected user data is no good to us if we can't remember and recall it.

Apple provides us with a very useful utility here that goes by the name of NSUserDefaults. This is basically a utility class that allows you to specify keys for which values must be persisted and by which we can later recall them again. The NSUserDefaults takes care of persisting and loading these key and value pairs for us, so we needn't worry about any of that. As a matter of fact; the most we'll ever need to considder the actual persistence of our data is when we're setting an important value that we want to flush straight away (such that it's not reset to the old value should our application crash before NSUserDefaults decides it's time to flush its cache). In that particular case, we need to invoke synchronize on our NSUserDefaults object:

[self.defaults synchronize];

One caveat: Since we're dealing with persisting data here, we need to make sure that the data we store is actually persistable. In this particular case, that means it should be an instance of: NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary. In the case of collections, they may only contain elements that are instances of the same list of classes. Should you like to persist any other data; you'll need to archive it into an NSData object and unarchive it on access.

What about initial default values?

While persisting new configuration data is great and all, we still need to actually have default settings for most of our configuration properties before the user has touched them. These can't come from our persistence object because we've never persisted anything with it before; or can they?

NSUserDefaults, our weapon of choice regarding the storage and accessing of our configuration data, comes to the rescue. It provides a means of specifying default values for each of our configuration properties. The default value is returned by NSUserDefaults whenever we try to look something up that doesn't already have a user-persisted value.

[self.defaults registerDefaults:[NSDictionary dictionaryWithObjectsAndKeys:
                                     [NSNumber numberWithInt: 24],       dFontSize,
                                     ...,
                                     nil]];

Accessing and modifying our settings

Great! We can store settings and recall them again later. Now if only we could actually access them from our application, that'd be awesome.

Let me ask you, what is the way for objects to provide other object access to their data? I'm sure you'll all agree with me that the answer to that is simply: Properties.

So that's what we'll use. Properties in Objective C are type-safe, they are short to declare and easy to access. We even get the choice between the [square bracket] and the dot.notation:

@property (readwrite, retain) NSNumber          *fontSize;

That's it. Your application now knows how to access the fontSize configuration setting. It can look it up, and it can change it. What's more is that all this is nice and type-safe. Remember to always use the retain attribute on these properties. As a matter of fact; remember to use retain (or copy) on all your object properties unless you have a very specific and educated reason not to.

Now, while our application knows how to get to your settings; your configuration implementation doesn't yet know how to link up our NSUserDefaults with these properties. This step is a little bit more complex than what we've done so far.

Simply put

In essence, what we need to accomplish is invoking -setObject:forKey: on our NSUserDefaults instance with the key being the name of our configuration property and the value being whatever the user instructed us to store for that setting.

We could do it quite simply by implementing the setter for the property like thus:

- (void)setFontSize:(NSNumber *)fontSize {
        
        [self.defaults setObject:fontSize forKey:dFontSize];
    }

Our setter takes the value given to us by the application and stores it into our NSUserDefaults. All done. Accessing the setting is as easy as:

- (NSNumber *)fontSize {
        
        return [self.defaults objectForKey:dFontSize];
    }

The problem this introduces, however, is massive code verbosity. And as agreed earlier; code verbosity leads to opaqueness and is bad. Moreover, the amount of copy-pasting that would be required when implementing a host of configuration properties should give any decent software architect a splitting headache.

Each of these configuration property implementations will look almost identical. All they need to do is invoke either -setObject:forKey: or -objectForKey: on our NSUserDefaults instance. We should be able to extract all that duplicate code into one single method, right?

Clean that up

Of course right! This is Objective C; all is possible at runtime! The solution here is to introduce the concept of Message Forwarding.

The idea is to watch as our application invokes our property and intercept that invocation.

Instead of providing an implementation of our properties, we'll stop Objective C from trying to find such implementation and instead forward it to a single method that does all.

Forwarding relies on two things:

Objective C needs to be able to create an NSInvocation object for your property's getter or setter.
We need to intercept each call to our properties with missing implementation and handle them manually.

Let's start with the first. Normally, an NSInvocation object is created by the Objective C runtime whenever a method is invoked by looking up the method signature for that method's selector on your object in your object's implementation. Our problem is that we don't have and implementation and therefore there is nothing for Objective C to generate a method signature from. We'll have to do this manually.

Since our methods are simple property getters and setters, they aren't all that complex to generate a method signature for. The signature comes from the way Objective C works internally. Any Objective C method call really just dereferences a C function pointer with a return value, the first argument being self and the second argument being _cmd which is the selector of the method that is being called.

Getters have a method signature that says: Return id, self is an id and _cmd is a SEL. That translates into an Objective C type array of: "@@:".

Setters have a method signature that says: Return void, self is an id, _cmd is a SEL and the first argument of my method is an id. This translates into an Objective C type array of: "v@:@".

Here's how we now generate the required method signatures from that information:

- (NSMethodSignature *)methodSignatureForSelector:(SEL)aSelector {
        
        if ([NSStringFromSelector(aSelector) hasPrefix:@"set"])
            return [NSMethodSignature signatureWithObjCTypes:"v@:@"];
        
        return [NSMethodSignature signatureWithObjCTypes:"@@:"];
    }

That's done. On to number two: Intercepting the call to our missing property implementation.

Whenever Objective C is asked to perform an invocation on a selector that is not defined in the object instance you're calling it on, the runtime invokes the -forwardInvocation: method of that object instance to give it a chance to forward the invocation elsewhere. The default implementation of this method simply just calls -doesNotRecognizeSelector: which raises an exception. This is what causes our applications to terminate when we invoke selectors on objects that do not support them.

We're going to override this default behaviour and implement our own.

The goal is simple: Either set the object the application is calling our setter with in the NSUserDefaults or retrieve it for the getter the application is calling.

The only thing we still need to know before we can write the whole implementation for this is the name of the key in our NSUserDefaults that we should use to store our property's data. This key name should be something we can easily generate from the data we have when we're in that property's setter or getter. I decided to use the string representation of the property's getter. This gives me two nice perks:

It's easy to generate while we're inside our -forwardInvocation: call.
It provides an additional level of type-safety.

Type safety? How? Here's how: Whenever you need to reference the key name of a property outside of the -forwardInvocation: call (for instance, when setting defaults for that property!), use NSStringFromSelector(@selector(myProperty)) as the key for NSUserDefaults.

Now, provided you have -Wundeclared-selector set in your build settings' WARNING_CFLAGS (also called Other Warning Flags), you'll get the compiler complaining whenever you reference non-existing settings or miss-spell them. Great for knowing what to else to delete or change when you're removing or renaming a configuration property!

That aside, we now know what our key will be. So, let's get started with our forwarding implementation; and wrap this up!

- (void)forwardInvocation:(NSInvocation *)anInvocation {
        
        NSString *selector = NSStringFromSelector(anInvocation.selector);
        if ([selector hasPrefix:@"set"]) {
            NSRange firstChar, rest;
            firstChar.location  = 3;
            firstChar.length    = 1;
            rest.location       = 4;
            rest.length         = selector.length - 5;
            
            selector = [NSString stringWithFormat:@"%@%@",
                        [[selector substringWithRange:firstChar] lowercaseString],
                        [selector substringWithRange:rest]];
            
            id value;
            [anInvocation getArgument:&value atIndex:2];
            
            [defaults setObject:value forKey:selector];
        }
        
        else {
            id value = [defaults objectForKey:selector];
            [anInvocation setReturnValue:&value];
        }
    }

It's really simple for when we're forwarding a getter. We just use the string representation of the invocation's selector and we have our key. For the setter we need to trim off the set prefix and lowercase the next character. That gives us the correct string representation.

Putting it all together

So, what we have now, is a single class that provides easy access to configuration properties and a dead-easy, type-safe way of adding new properties or refactoring (renaming/deleting) old properties.

Here's what this all looks like put together. Our tiny interface that defines all our configuration properties in beautiful simplicity:

@interface Config : NSObject {
    
        NSUserDefaults                              *defaults;
    }
    
    @property (readwrite, retain) NSNumber          *fontSize;
    ...
    
    + (Config *)get;
    
    @end

Our slightly more complex but safe and (relatively) short implementation:

#define dFontSize                               NSStringFromSelector(@selector(fontSize))
    
    @interface Config ()
    
    @property (readwrite, retain) NSUserDefaults    *defaults;
    
    @end
    
    
    @implementation Config
    
    @synthesize defaults;
    @dynamic fontSize, ...;
    
    - (id)init {
        
        if (!(self = [super init]))
            return nil;
        
        self.defaults = [NSUserDefaults standardUserDefaults];
        [self.defaults registerDefaults:[NSDictionary dictionaryWithObjectsAndKeys:
                                         [NSNumber numberWithInt: 24],       dFontSize,
                                         ...,
                                         nil]];
        
        return self;
    }
    
    - (void)dealloc {
        
        self.defaults = nil;
        
        [super dealloc];
    }
    
    + (Config *)get {
        
        static Config *configInstance;
        if(!configInstance)
            configInstance = [[Config alloc] init];
        
        return configInstance;
    }
    
    - (NSMethodSignature *)methodSignatureForSelector:(SEL)aSelector {
        
        if ([NSStringFromSelector(aSelector) hasPrefix:@"set"])
            return [NSMethodSignature signatureWithObjCTypes:"v@:@"];
        
        return [NSMethodSignature signatureWithObjCTypes:"@@:"];
    }
    
    - (void)forwardInvocation:(NSInvocation *)anInvocation {
        
        NSString *selector = NSStringFromSelector(anInvocation.selector);
        if ([selector hasPrefix:@"set"]) {
            NSRange firstChar, rest;
            firstChar.location  = 3;
            firstChar.length    = 1;
            rest.location       = 4;
            rest.length         = selector.length - 5;
            
            selector = [NSString stringWithFormat:@"%@%@",
                        [[selector substringWithRange:firstChar] lowercaseString],
                        [selector substringWithRange:rest]];
            
            id value;
            [anInvocation getArgument:&value atIndex:2];
            
            [self.defaults setObject:value forKey:selector];
        }
        
        else {
            id value = [self.defaults objectForKey:selector];
            [anInvocation setReturnValue:&value];
        }
    }
    
    @end

Application sales statistics from the CLI

2009-05-03T09:44:00.002+02:00

The problem

Apple provides us, developers, with sales data which nicely details which of our applications have sold when and to whom. This data comes in the form of gzipped plain text files that use a CSV-like format (in fact, tab-delimited) of encoding data fields.

That's not exactly very human-readable. And while Apple provides a quick and simple "preview" button for these reports, it's hardly useful either. What we'd like to see is some statistics on how many applications we've sold in total, to whom, in what currencies, what countries and most importantly, how much profit it's made us!

Sadly, Apple does not provide, but they do give us what we need to roll our own solution. And many have. There are applications all around that parse these reports Apple gives us and render them in graphs or dump them in tables. Unfortunately, almost all of these are made by developers that like to charge. I haven't come across anything noteworthy that's freeware.

The solution

How would I solve this problem? Easy enough, I'm a developer; I might as well roll up my sleeves and get started myself. And I did.

I decided that what I wanted was something simple and fast. I didn't need the charts, all I wanted was to know how much I'd sold since the last time I checked and what my profit meter looked like so far. I'm a CLI-guy, so I wanted a way of running something from the CLI and immediately getting all the feedback I'm interested in.

Enter: iphone-stats

So I opened my vim and got to it. The result is a series of bash scripts that do everything I'm interested in for the moment. They parse my sales data (which is daily sales reports nicely organized in subdirectories named after their month) and write out some statistics on my terminal. Moreover, scripts are also provided that fetch iTunes App Store reviews on my applications and fetch my daily iTunes Connect reports for me through a cron job.

Here's what the first script, stats, looks like:

A second script, reviews, downloads customer reviews from the iTunes App Stores world-wide. This is a great way of keeping track what people are saying about your applications.

Here's what that looks like:

A third script, fetchdailies is a script that checks which the last daily report that you have is and downloads any available dailies past that. You can run it quickly from the CLI, like the other scripts, and it'll tell you what it's doing, or you can schedule it in a cron job so that it'll automatically download your available dailies for you every day.

The last script uses a python script called appdailysales, which is not mine, but is an open-source script written mostly by Kirby Turner. I've adapted it for security (of passing the password) and integration (with iphone-stats). You can, of course, invoke it directly. It has good help output if you start it with the -h argument:

Availability

The whole bundle of scripts is available from the (quick and dirty) iphone-stats homepage at:

http://www.lhunath.com/iphone-stats

I recommend you go through the README file contained within: It details the use very well and in great detail. Of course, you can also contact me directly if you have any issues.

The memory management battle that wins the war.

2009-04-19T17:30:00.003+02:00

From Java to (Objective) C

I used to be a Java guy. Java, the language of type safety, UIs that stick out like a sore thumb, and a VM that sucks your RAM dry; yes, I was all for it. I loved the simplicity with which you express relationships, the trust you have that compilable code (if written sanely) is safe, the beauty of IoC and unit testing, you name it.

Understandably, I was struck with horror and panic when I realized that my new ambition, iPhone development, would require me stepping away from all that. I soon learned that Objective C, while a beautiful and respectable language in its own league, is nowhere as safe as Java. Everything you do in it is dangerous: Half of the problems are only detectable at run-time, refactoring in and indexing it is a nightmare (mostly because of its inheritly dynamic nature) and there's really no decent IDE for it.

Trade-offs

At the same time, all this playing with fire also adds some compelling new ways of getting things done. Where Java has reflection, Objective C goes so much further in a far cleaner way.

To those that have already dipped their fingers in the Java reflection sauce it's clear what an absolute mess your code soon becomes. The beauty of simplicity that Java can be becomes a horrid web of loosely-coupled constructs that affect each other in most unpredictable ways. Reflection is the name of the Java-antichrist, here to tempts us into ruining everything good and pure about writing in the Java language.

Objective C, being a very flexible language by its very nature, provides a bunch of interesting similar features. Admittedly, though, it does it with style. Categories, dynamic properties, pointers, you name it. They're all very nicely integrated into the language and don't bloat or worsen the type-safety of the code too much. Granted, you don't start off from the same level of type safety either.

All this flexibility comes at a very important price, though. Very little about the code is certain at compile-time. While you can convince the compiler to warn you of most bad practices and eliminate a large part of possible bugs that the Java compiler wouldn't even agree to compile, and while sticking to sane code practices goes a long way, you are never certain that your code won't cause illegal pointer dereferencing, method calls on objects that don't even have those methods or allow buffer overflows. These are things that are almost impossible in Java (provided you aren't tinkering with reflection - and even then there's an impecible exceptions framework with checked exceptions that has your back).

The baddest of the bunch, the nastiest of nasties, the meanest of the meanies, is, still memory (pointer) management. While there are very good rules about what you should and shouldn't be doing, I want to be able to trust that the code I have runs perfectly. I don't want to be called by QA or see customers complain: I want my compiler to complain before anyone else sees the stupid mistake I made late last night.

Enter: Properties

Objective C 2.0 has some very interesting features that help with memory management. Sadly, some are not available in the work I'm doing. Since I'm an iPhone developer, I cannot benefit from the garbage collection, for instance. That is a feature privileged for those blessed Mac developers.

Something that is available to iPhone developers: properties. Properties are the what I have dreamt of since the first week I set foot on Java soil. They are a type-safe, simple and clean way of defining and declaring instance variable accessors and setters. Many languages have a variant of these, sometimes with the same or a different name, except for Java. In Java you're still forced to explicitly declare getters and setters for each and every instance variable that you want to reveal to the outside world in a safe and encapsulated object-oriented type of way.

Not only are they beautifully simple, they also pack a punch: Properly used property declarations are the answer to all your memory management woes.

How properties will save your life

The beauty of properties lies in the fact that the compiler uses them to generate getters and setters that do all the important work for you. The code that is generated depends on the hints you specify in the property definition: The property attributes. These attributes make sure that access to the instance variable that backs the property is done in a insistent and safe way.

We can declare the following attributes on our properties:

readonly/readwrite: Specify whether we need just a getter or also a setter.
nonatomic: Specify whether we need access to the property to be atomic (synchronous) or not.
retain/copy/assign: Specify whether the type of memory management we need to perform on the property.
The way most people use properties is quite straight forward. They declare an instance variable in their class header, add a property to it with the same name and type, specify appropriate attributes and synthesize them in the respective class implementation block.

The beauty of properties is that they provide a central and trustworthy way of declaring how our instance variables must be used. For instance, specifying retain on our property means that every time we assign a value to the property the generated setter will release any existing object assigned to the instance variable and retain the new object before assigning it to the instance variable.

While the use of well-defined properties results in perfectly safe code, problems can still occur when we go behind the property's back. There are two things we can do to mess things up:

Accessing the instance variable directly.
Invoking retain, release, autorelease or, God forbid, dealloc on the object in our property ourselves.
I said "well-defined" because, understandably, using incorrect attributes on our properties will also mess things up. The best example of badly defined properties is NSObject-typed properties with the assign attribute. Objects should always have the retain or copy attribute. Objects with the assign attribute are weak links. That means that our property does not take part in the memory management of the object. As a result, whenever the party that does take part in the memory management of the object decides it's done with it and causes it to get deallocated, our property might still reference the object. The results are predictable: application crash imanent.

Knowing that, the answer to all our worries is: "Hands off of property managed memory!". In practice, this means avoiding the above two at all costs.

You should never access instance variables directly: Use the property provided accessor methods for that. They provide an encapsulated and safe way of accessing our instance variables. There should never be a reason to access the instance variable directly.

You should also never send memory management messages to any objects managed by properties. Properties rely on the managed objects' retain state to be as they set it. Whenever you send messages directly to the managed objects you will break that reliance, and with it, your code.

Asserting the rules

While it's great to know good coding practices, knowing them doesn't assert that our code is safe. It's easy to slip up, especially so when multiple developers work on the same codebase. For this reason, it's important to put into effect code practices that help us make sure we abide by the rules, and help us detect whenever we don't or prevent us from breaking them.

As mentioned before, there are three important things we need to keep in mind: avoiding direct ivar access, avoiding manual memory management and using the correct property attributes. The last two are really a matter of keeping your head when coding: we can't do much to enforce this at compile-time.

To aid us stick to the first, though, I recommend the following code style. It encourages object encapsulation and discourages, but more importantly, makes direct instance variable access very noticable.

We begin with our interface declaration:

Foo.h:

@interface Foo : NSObject {
        @private
        NSString                                *_name;
        NSArray                                 *_friends;
    }
    
    @property (readonly, copy)      NSString    *name;
    @property (readonly, retain)    NSArray     *friends;
    
    -(id) initWithName:(NSString *) name
            andFriends:(NSArray *)  friends;
    
    @end

Things to note here are the underscore-prefixed instance variables and the copy/retain attributes on readonly property definitions. We use underscore-prefixed instance variables because the only place where we want to reference our instance variables is when we synthesize our properties. Underscore-prefixing them makes it very unlikely we'll ever accidentally reference them from implementation code and means whenever we do, it stands out like a sore thumb in our code. The copy and retain on readonly properties is to avoid a compiler warning which will be caused by our later redefinition of those properties:

Foo.m:

@interface Foo ()
    
    @property (readwrite, copy)     NSString    *name;
    @property (readwrite, retain)   NSArray     *friends;
    
    @end

This is a class extension which we put in our implementation file. It overrides the property definitions from earlier making them readwrite instead of readonly. However, the setter will only be visible to the implementation, not to anyone using our class. Considder it a private setter. If you need your setter to be public, however, there's no need for this and you should just make it readwrite in the header file. Now, on to our implementation:

Foo.m:

@implementation Foo
    
    @synthesize name    = _name;
    @synthesize friends = _friends;
    
    -(id) initWithName:(NSString *) name
            andFriends:(NSArray *)  friends {
    
        if(!(self = [super init]))
            return nil;
    
        self.name       = name;
        self.friends    = friends;
    
        return self;
    }
    
    -(void) dealloc {
    
        self.name       = nil;
        self.friends    = nil;
    
        [super dealloc];
    }
    
    @end

Notice how in the we need to specify the name of the instance variables that will back our properties in their synthesize declarations. That's because the property name is not the same as the instance variable name. It's also the only place in your code you should reference your instance variables. Beyond that, you'll be using the properties whenever you need to access or set the instance variable's data. Even in the dealloc method you'll be using only just your properties. Setting them to nil will cause the object held by the respective instance variable to get released if the property is set to retain or copy. This means no explicit memory management and centralized memory management configuration per property.

A brave attempt at something new.

2009-04-18T21:35:00.003+02:00

Yet another weblog

Rambling. It's a favorite past-time of anyone self-respecting. We see the people around us doing stupid things and feel the irresistable need to ramble about it. Even though we all make mistakes, and we all do stupid things, it somehow makes us feel better pointing out just how badly some people got it wrong.

The unstoppable evolution of the new web has blessed all us ramblers with a giant gateway to broadcast our ramblings to the rest of the world. Oddly enough, it appears this practice has in fact become truly popular. Web logs pop up all over the place with countless providers trying to pull in anyone with enough time to perform a brain-dump every so often. The practice has even turned profitable. Why? It appears that not only is it in our very human nature to have an opinion on everything and a desire to share it with everyone, it is also truly addictive to follow fellow ramblers and keep up on the latest gossip.

RSS feeds are more popular than ever before and millions of hours of work are wasted every single day by people reading others' web logs instead of doing what they're payed to do. Alas, such is the recent turn of events, and for better or for worse, it's a perfectly natural evolution of our very nature.

Really no different than the rest of them

Contradictory to what the above introduction might elude to, I'm really no different than the rest of them. I have my opinions, and more often than not, they're hardly as educated as I might pretend.

Therefore, I've decided it's time I join the ranks and open up a web log for anyone with unwasted time left to read and follow.

Subject

The main subjects you'll find lurking in the entries here will be those I'm generally most vocal about:

Bash Shell Scripting
Java Design and Development
iPhone Development and Objective C