Release/3.0

.gitmodules

@@ -1,6 +1,3 @@
-[submodule "Tests/Support/Vendor/Specta"]
-	path = Tests/Support/Vendor/Specta
-	url = https://github.com/specta/specta.git
-[submodule "Tests/Support/Vendor/Expecta"]
-	path = Tests/Support/Vendor/Expecta
-url=https://github.com/tonyarnold/expecta.git
+[submodule "Tests/Vendor/Expecta"]
+	path = Tests/Vendor/Expecta
+	url = https://github.com/specta/expecta.git

.travis.yml

@@ -0,0 +1,3 @@
+language: objective-c
+script: Tests/Support/Scripts/objc-build-scripts/cibuild
+osx_image: mavericks

Changelog.md → CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## Version 3.0
+
+MagicalRecord 3.0 is a major release with new features and breaking changes.
+
+### Stacks
+
+MagicalRecord 3.0 introduces the concept of a 'Stack'. Applications can have a single stack, or many stacks. Library style applications like iPhoto or iTunes might only use a single stack, whereas a document-based application like TextEdit would usually use a stack for every open document.
+
+It's easiest to think about a stack as all of the components necessary to interact with a single persistent store.
+
+A stack includes the following basic objects:
+
+```objc
+@property (nonatomic, copy) NSString *stackName;
+
+@property (nonatomic, strong) NSManagedObjectContext *context;
+@property (nonatomic, strong) NSManagedObjectModel *model;
+@property (nonatomic, strong) NSPersistentStoreCoordinator *coordinator;
+@property (nonatomic, strong) NSPersistentStore *store;
+```
+
+To migrate a simple, existing MagicalRecord-based application to use stacks, it's as simple as replacing this:
+
+```objc
+[MagicalRecord setupAutoMigratingCoreDataStack];
+```
+
+with:
+
+```objc
+[MagicalRecordStack setDefaultStack:[AutoMigratingMagicalRecordStack stack]];
+```
+
+We recommend that you keep a reference to your stack somewhere other than the `defaultStack` property of the MagicalRecordStack class, so that if you need to add more than one stack it's an easier upgrade path. Also, Saul gets a bit crazy when people use singletons.
+
+There are 9 stacks included by default:
+
+#### SQLite Backed Stacks
+
+All of the stacks below use SQLite-backed persistent stores (NSSQLiteStoreType).
+
+1. **AutoMigratingMagicalRecordStack** will automatically perform all migrations provided by your project.
+
+2. **AutoMigratingWithSourceAndTargetModelMagicalRecordStack** allows you define source and target managed object models to migrate directly between. It will not perform any additional migrations beyond those necessary to upgrade from the source model to the target.
+
+3. **SQLiteMagicalRecordStack** provides a context that uses main queue concurrency.
+
+4. **SQLiteWithSavingContextMagicalRecordStack** in addition to the main queue context, this stack provides a second, private background context that can be used to save changes without blocking the main thread.
+
+3. **ClassicSQLiteMagicalRecordStack** provides a context that uses confinement concurrency when saving.
+
+4. **ClassicWithBackgroundCoordinatorSQLiteMagicalRecordStack** in addition to the main queue context, provides a second, private background context that can be used to save changes without blocking the main thread.
+
+4. **ManuallyMigratingMagicalRecordStack** does not automatically infer the mapping models to be used when performing migrations (`NSInferMappingModelAutomaticallyOption : NO` ).
+
+#### iCloud Stack
+
+**iCloudMagicalRecordStack** provides a SQLite-backed persistent store that configures a Ubiquity Container for iCloud.
+
+#### In-Memory Stack
+
+**InMemoryMagicalRecordStack** provides an in-memory persistent store. In-memory stacks are great for running import processes, or for use in your tests.
+
+
+## Deprecations
+
+* `MR_SHORTHAND` is deprecated in this release. You can continue using the shorthand methods, however clang will show a warning. If you absolutely must silence the deprecation warning, define `WE_PROMISE_TO_MIGRATE_TO_MAGICALRECORD_3_0` before you import any MagicalRecord header. Any method marked as deprecated in this release will be removed entirely in MagicalRecord 4.0, so please use these warnings to migrate your code to the non-shorthand methods.
+* The **NSManagedObjectContext+MagicalThreading category has been removed entirely**. These methods are unnecessary alongside GCD, NSOperation and the `-performBlock:` and `-performBlockAndWait:` methods on NSManagedObjectContext. This includes the following methods:
+    - `+ (NSManagedObjectContext *) MR_contextForCurrentThread;`
+    - `+ (void) MR_clearNonMainThreadContextsCache;`
+    - `+ (void) MR_resetContextForCurrentThread;`
+    - `+ (void) MR_clearContextForCurrentThread;`
+
+
+
 ## Version 2.2
 * Updated examples and fixed errors in README - [Tony Arnold](mailto:tony@thecocoabots.com)
 * Changes block saves to use child context of rootSavingContext so that large saves do not channel through the default context and block the main thread - r-peck

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+Thanks for contributing to this project!
+
+To make the process as easy as possible, we've got a few guidelines that we'd appreciate you following:
+
+## Filing Issues
+
+Before you file an issue, please ensure that:
+
+1. **It's a bug or a feature request** — if you're looking for help using MagicalRecord, please ask your question on [Stack Overflow](http://stackoverflow.com/). We monitor the [**MagicalRecord** tag](http://stackoverflow.com/questions/tagged/magicalrecord) so be sure to tag your question so that we see it
+1. **Search for an existing issue** — there's a good chance you're not the only one experiencing the problem you've come to tell us about
+2. **Include as much information as you can** — if we can't reproduce the problem you've filed, we can't fix it. Include crash logs, exception reports and code if you can.
+
+## We Prefer Pull Requests
+
+If you know exactly how to implement the feature being suggested or fix the bug being reported, please open a pull request instead of an issue. Pull requests are easier than patches or inline code blocks for discussing and merging the changes. Please ensure that you include tests in the Pull Request — we use XCTest with [Expecta](http://github.com/specta/expecta/).
+
+If you can't make the change yourself, please open an issue after making sure that one isn't already logged.
+
+## Contributing Code
+
+Fork this repository, make some great changes (preferably in a branch named for the topic of the changes you're making) and send a pull request!
+
+All code contributions should match our [coding conventions](/magicalpanda/MagicalRecord/wiki/Coding-Conventions).
+
+Thanks for reading the guidelines!

Docs/Fetching.md

@@ -2,132 +2,149 @@
 
 #### Basic Finding
 
-Most methods in MagicalRecord return an NSArray of results. So, if you have an Entity called Person, related to a Department (as seen in various Apple Core Data documentation), to get all the Person entities from your Persistent Store:
+Most methods in MagicalRecord return an `NSArray` of results.
 
-	//In order for this to work you need to add "#define MR_SHORTHAND" to your PCH file
-	NSArray *people = [Person findAll];
+Say you have an Entity called "Person", related to a Department (as seen in various Apple Core Data documentation). To get all of the Person entities from your Persistent Store, use the following method:
 
-	// Otherwise you can use the longer, namespaced version
-	NSArray *people = [Person MR_findAll];
+```objective-c
+NSArray *people = [Person MR_findAll];
+```
 
-Or, to have the results sorted by a property:
+Or, to return the results sorted by a property:
 
-	NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName" ascending:YES];
+```objective-c
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName" ascending:YES];
+```
 
-Or, to have the results sorted by multiple properties:
+Or, to return the results sorted by multiple properties:
 
-        NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName" ascending:YES];
+```objective-c
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName" ascending:YES];
+```
 
-Or, to have the results sorted by multiple properties with difference attributes - will default to whatever you set it to:
+Or, to return the results sorted by multiple properties with different attributes (these will default to whatever you set them to):
 
-        NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName:NO,FirstName" ascending:YES];
+```objective-c
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName:NO,FirstName" ascending:YES];
 
-        NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName:YES" ascending:NO];
+// OR
 
-If you have a unique way of retrieving a single object from your data store, you can get that object directly:
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName:YES" ascending:NO];
+```
 
-	Person *person = [Person MR_findFirstByAttribute:@"FirstName" withValue:@"Forrest"];
+If you have a unique way of retrieving a single object from your data store (such as via an identifier), you can use the following method:
+
+```objective-c
+Person *person = [Person MR_findFirstByAttribute:@"FirstName" withValue:@"Forrest"];
+```
 
 #### Advanced Finding
 
 If you want to be more specific with your search, you can send in a predicate:
 
-	NSArray *departments = [NSArray arrayWithObjects:dept1, dept2, ..., nil];
-	NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
-
-	NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
+```objective-c
+NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", @[dept1, dept2]];
+NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
+```
 
 #### Returning an NSFetchRequest
 
-	NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
-
-	NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
+```objective-c
+NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
+NSFetchRequest *people = [Person MR_requestAllWithPredicate:peopleFilter];
+```
 
 For each of these single line calls, the full stack of NSFetchRequest, NSSortDescriptors and a simple default error handling scheme (ie. logging to the console) is created.
 
 #### Customizing the Request
 
-	NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
+```objective-c
+NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
 
-	NSFetchRequest *peopleRequest = [Person MR_requestAllWithPredicate:peopleFilter];
-	[peopleRequest setReturnsDistinctResults:NO];
-	[peopleRequest setReturnPropertiesNamed:[NSArray arrayWithObjects:@"FirstName", @"LastName", nil]];
-	...
+NSFetchRequest *peopleRequest = [Person MR_requestAllWithPredicate:peopleFilter];
+[peopleRequest setReturnsDistinctResults:NO];
+[peopleRequest setReturnPropertiesNamed:@[@"FirstName", @"LastName"]];
 
-	NSArray *people = [Person MR_executeFetchRequest:peopleRequest];
+NSArray *people = [Person MR_executeFetchRequest:peopleRequest];
+```
 
 #### Find the number of entities
 
-You can also perform a count of entities in your Store, that will be performed on the Store
+You can also perform a count of all entities of a specific type in your Persistent Store:
 
-	NSNumber *count = [Person MR_numberOfEntities];
+```objective-c
+NSNumber *count = [Person MR_numberOfEntities];
+```
 
 Or, if you're looking for a count of entities based on a predicate or some filter:
 
-	NSNumber *count = [Person MR_numberOfEntitiesWithPredicate:...];
-	
-There are also counterpart methods which return NSUInteger rather than NSNumbers:
+```objective-c
+NSNumber *count = [Person MR_numberOfEntitiesWithPredicate:...];
+```
 
-* countOfEntities
-* countOfEntitiesWithContext:(NSManagedObjectContext *)
-* countOfEntitiesWithPredicate:(NSPredicate *)
-* countOfEntitiesWithPredicate:(NSPredicate *) inContext:(NSManagedObjectContext *)
+There are also complementary methods which return `NSUInteger` rather than `NSNumber` instances:
+
+* `MR_countOfEntities`
+* `MR_countOfEntitiesWithContext:(NSManagedObjectContext *)context`
+* `MR_countOfEntitiesWithPredicate:(NSPredicate *)predicate`
+* `MR_countOfEntitiesWithPredicate:(NSPredicate *)predicatecontext inContext:(NSManagedObjectContext *)`
 
 #### Aggregate Operations
 
-    NSPredicate *predicate = [NSPredicate predicateWithFormat:@"diaryEntry.date == %@", today];
-    int totalFat = [[CTFoodDiaryEntry MR_aggregateOperation:@"sum:" onAttribute:@"fatColories" withPredicate:predicate] intValue];
-    int fattest  = [[CTFoodDiaryEntry MR_aggregateOperation:@"max:" onAttribute:@"fatColories" withPredicate:predicate] intValue];
-
+```objective-c
+NSInteger totalFat = [[CTFoodDiaryEntry MR_aggregateOperation:@"sum:" onAttribute:@"fatCalories" withPredicate:predicate] integerValue];
+NSInteger fattest  = [[CTFoodDiaryEntry MR_aggregateOperation:@"max:" onAttribute:@"fatCalories" withPredicate:predicate] integerValue];
+NSArray *caloriesByMonth = [CTFoodDiaryEntry MR_aggregateOperation:@"sum:" onAttribute:@"fatCalories" withPredicate:predicate groupBy:@"month"];
+```
+
 #### Finding from a different context
 
 All find, fetch, and request methods have an inContext: method parameter
 
-	NSManagedObjectContext *someOtherContext = ...;
-
-	NSArray *peopleFromAnotherContext = [Person MR_findAllInContext:someOtherContext];
+```objective-c
+NSArray *peopleFromAnotherContext = [Person MR_findAllInContext:someOtherContext];
 
-	...
-
-	Person *personFromContext = [Person MR_findFirstByAttribute:@"lastName" withValue:@"Gump" inContext:someOtherContext];
-
-	...
-
-	NSUInteger count = [Person MR_numberOfEntitiesWithContext:someOtherContext];
+Person *personFromContext = [Person MR_findFirstByAttribute:@"lastName" withValue:@"Gump" inContext:someOtherContext];
 
+NSUInteger count = [Person MR_numberOfEntitiesWithContext:someOtherContext];
+```
 
 ## Creating new Entities
 
 When you need to create a new instance of an Entity, use:
 
-	Person *myNewPersonInstance = [Person MR_createEntity];
+```objective-c
+Person *myPerson = [Person MR_createEntity];
+```
 
-or, to specify a context:
-
-	NSManagedObjectContext *otherContext = ...;
-
-	Person *myPerson = [Person MR_createInContext:otherContext];
+or, to specify which context the entity is inserted into:
 
+```objective-c
+Person *myPerson = [Person MR_createEntityInContext:otherContext];
+```
 
 ## Deleting Entities
 
 To delete a single entity:
 
-	Person *p = ...;
-	[p  MR_deleteEntity];
-
-or, to specify a context:
+```objective-c
+[myPerson MR_deleteEntity];
+```
 
-	NSManagedObjectContext *otherContext = ...;
-	Person *deleteMe = ...;
+or, to delete the entity from a specific context:
 
-	[deleteMe MR_deleteInContext:otherContext];
+```objective-c
+[myPerson MR_deleteEntityInContext:otherContext];
+```
 
 There is no delete *All Entities* or *truncate* operation in core data, so one is provided for you with Active Record for Core Data:
 
-	[Person MR_truncateAll];
+```objective-c
+[Person MR_truncateAll];
+```
 
-or, with a specific context:
+or, to truncate all entities in a specific context:
 
-	NSManagedObjectContext *otherContext = ...;
-	[Person MR_truncateAllInContext:otherContext];
+```objective-c
+[Person MR_truncateAllInContext:otherContext];
+```

Docs/GettingStarted.md

@@ -3,7 +3,7 @@
 
 ## Setting up the Core Data Stack
 
-To get started, first, import the header file *CoreData+MagicalRecord.h* in your project's pch file. This will allow a global include of all the required headers.
+To get started, first, import the header file *MagicalRecord.h* in your project's pch file. This will allow a global include of all the required headers.
 Next, somewhere in your app delegate, in either the applicationDidFinishLaunching:(UIApplication \*) withOptions:(NSDictionary \*) method, or awakeFromNib, use **one** of the following setup calls with the **MagicalRecord** class:
 
 	+ (void) setupCoreDataStack;

Docs/Installation.md

@@ -1,8 +1,8 @@
 # Installation
 
-1. In your XCode Project, drag the *MagicalRecord* folder (under the main folder) into your project. 
-2. Add *CoreData+MagicalRecord.h* file to your PCH file or your AppDelegate file.
-3. Optionally preceed the *CoreData+MagicalRecord.h* import with `#define MR_SHORTHAND` to your PCH file if you want to use MagicalRecord methods without the *MR_prefix* like `findAll` instead of `MR_findAll`
+1. In your Xcode Project, drag the *MagicalRecord* folder (under the main folder) into your project. 
+2. Add *MagicalRecord.h* file to your PCH file or your AppDelegate file.
+3. Optionally precede the *MagicalRecord.h* import with `#define MR_SHORTHAND` to your PCH file if you want to use MagicalRecord methods without the *MR_prefix* like `findAll` instead of `MR_findAll`
 4. Start writing code!
 
 # Requirements