cooksimo / nlcoredata Goto Github PK

NLCoreData is meant as a drop-in wrapper for most of your Core Data needs on iOS (untested on OS X).
Requires ARC. Requres iOS 4+.

Goals
-----
* Write less code.
* Make code more readable.
* More compile-time checks.

You access convenience methods for insertion, deletion, counting and fetching through class
and instance methods on your NSManagedObject subclasses.

You no longer access objects by typing an NSString with an entity name, instead you use the entity class.
Instead of @"Person", use [Person class]. This provides a compile-time typo check.


NLCoreData is not for you if
----------------------------
* you need more than one persistent store.
* you don't want to subclass NSManagedObject


Initialization
--------------
If your Core Data model is named to something other than the name of your main bundle, you need to set the model name
before first use. Typically in application:didFinishLaunchingWithOptions:.

	[[NLCoreData shared] setModelName:@"MyCoreDataModel"];

You have to option to supply a pre-seeded sqlite database. First, check so that Core Data isn't initialized yet.
Typically in application:didFinishLaunchingWithOptions: on your first run:

	if ([[NLCoreData shared] storeExists] == NO)
		[[NLCoreData shared] usePreSeededFile:pathToMyFile];


Contexts
--------
NLCoreData provides lazily loaded shared NSManagedObjectContexts for all threads. To access:

	NSManagedObjectContext* context = [NSManagedObjectContext contextForThread];
	
Or if you're in a threaded environment and you want the context for the UI thread:

	NSManagedObjectContext* context = [NSManagedObjectContext contextForThread:[NSThread mainThread]];

To save a context:

	BOOL success = [context save];
	

Methods
-------
If you want to fetch all Person objects in your shared context:

	NSArray* results = [Person fetchWithPredicate:nil];

If you want to delete all Person objects in the context myContext:

	[Person deleteWithRequest:nil context:myContext];
	
If you want to count all Person objects that match the predicate myPredicate:

	NSUInteger count = [Person countWithPredicate:myPredicate];

	
Fetching
--------
You can fetch either an array of objects or a single object. If you want all Person objects in the shared context:

	NSArray* results = [Person fetchWithPredicate:nil];
	
If you want a single object in the shared context:

	Person* person = [Person fetchSingleAtIndex:0 withPredicate:nil];

The single fetch can be useful if there is only one object of that type, or if you provide a predicate
that you're certain only matches one object.

In some cases, you want to return a single object, or create one if it doesn't exist:

	Person* person = [Person fetchOrInsertSingle:0 withPredicate:nil];


Context interactivity
---------------------
Merge a context with the main context (e.g., after downloading and inserting data in the background):

	[context mergeWithContextOnThread:[NSThread mainThread] completion:^(NSNotification* note) {
		
		// handle data here
	}];


Fetch Requests
--------------
If you need to create an NSFetchRequest (e.g., for use in an NSFetchedResultsController),
you can do that with a provided convenience method:

	NSFetchRequest* request = [NSFetchRequest fetchRequestWithEntity:[Person class]];

The somewhat cumbersome setSortDescriptors: is augmented by sortByKey:ascending:
Though setSortDescriptors: is still available, don't use both on the same NSFetchRequest.

	[request sortByKey:@"myKeyPath" ascending:NO];
	[request sortByKey:@"mySecondaryKeyPath" ascending:YES];


Notes
-----
* Make sure you subclass all your Core Data entities, and that the subclasses are named for their entity
	(i.e., if you have an entity named Person, you need a subclass named Person).
* I strongly recommend using mogenerator. It's quite excellent. Get it here: http://rentzsch.github.com/mogenerator

Setup
-----
1. Add the NLCoreData folder to your project.
2. #import "NLCoreData.h" where you need it (in prefix.pch for easy access).
3. Optionally, set modelName to what your model is named: [[NLCoreData shared] setModelName:@"MyModel"];

Step 3 is skippable if your model name is the same as your bundle/app name.