WIP: documentation

CoreStoreTests/CoreStoreTests.swift

@@ -88,11 +88,6 @@ class CoreStoreTests: XCTestCase {
             obj1.testString = "lololol"
             obj1.testNumber = 42
             obj1.testDate = NSDate()
-            let objID = transaction.queryValue(
-                From(TestEntity1),
-                Select<NSManagedObjectID>(.Attribute("testEntityID"))
-            )
-            print(objID)
             
             let count = transaction.queryValue(
                 From<TestEntity1>(),

Sources/CoreStore.swift

@@ -38,8 +38,8 @@ public enum CoreStore {
     
     /**
      The default `DataStack` instance to be used. If `defaultStack` is not set before the first time accessed, a default-configured `DataStack` will be created.
-     
+     - SeeAlso: `DataStack`
-     Changing the `defaultStack` is thread safe, but it is recommended to setup `DataStacks` on a common queue (e.g. the main queue).
+     - Note: Changing the `defaultStack` is thread safe, but it is recommended to setup `DataStacks` on a common queue (e.g. the main queue).
      */
     public static var defaultStack: DataStack {
         

Sources/CoreStoreError.swift

@@ -29,6 +29,9 @@ import CoreData
 
 // MARK: - CoreStoreError
 
+/**
+ All errors thrown from CoreStore is expressed in `CoreStoreError` enum values.
+ */
 public enum CoreStoreError: ErrorType, CustomStringConvertible, CustomDebugStringConvertible, Hashable {
     
     /**

Sources/Fetching and Querying/Concrete Clauses/Select.swift

@@ -107,8 +107,8 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
         
         return ._Aggregate(
             function: "average:",
-            keyPath,
+            keyPath: keyPath,
-            As: alias ?? "average(\(keyPath))",
+            alias: alias ?? "average(\(keyPath))",
             nativeType: .DecimalAttributeType
         )
     }
@@ -129,8 +129,8 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
         
         return ._Aggregate(
             function: "count:",
-            keyPath,
+            keyPath: keyPath,
-            As: alias ?? "count(\(keyPath))",
+            alias: alias ?? "count(\(keyPath))",
             nativeType: .Integer64AttributeType
         )
     }
@@ -151,8 +151,8 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
         
         return ._Aggregate(
             function: "max:",
-            keyPath,
+            keyPath: keyPath,
-            As: alias ?? "max(\(keyPath))",
+            alias: alias ?? "max(\(keyPath))",
             nativeType: .UndefinedAttributeType
         )
     }
@@ -173,8 +173,8 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
         
         return ._Aggregate(
             function: "min:",
-            keyPath,
+            keyPath: keyPath,
-            As: alias ?? "min(\(keyPath))",
+            alias: alias ?? "min(\(keyPath))",
             nativeType: .UndefinedAttributeType
         )
     }
@@ -195,12 +195,33 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
         
         return ._Aggregate(
             function: "sum:",
-            keyPath,
+            keyPath: keyPath,
-            As: alias ?? "sum(\(keyPath))",
+            alias: alias ?? "sum(\(keyPath))",
             nativeType: .DecimalAttributeType
         )
     }
     
+    /**
+     Provides a `SelectTerm` to a `Select` clause for querying the `NSManagedObjectID`.
+     ```
+     let objectID = CoreStore.queryValue(
+         From(MyPersonEntity),
+         Select<NSManagedObjectID>(),
+         Where("employeeID", isEqualTo: 1111)
+     )
+     ```
+     - parameter keyPath: the attribute name
+     - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "objecID" is used
+     - returns: a `SelectTerm` to a `Select` clause for querying the sum value for an attribute
+     */
+    public static func ObjectID(As alias: KeyPath? = nil) -> SelectTerm {
+        
+        return ._Identity(
+            alias: alias ?? "objectID",
+            nativeType: .ObjectIDAttributeType
+        )
+    }
+    
     
     // MARK: StringLiteralConvertible
     
@@ -231,6 +252,9 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
             
         case ._Aggregate(let function, let keyPath, let alias, let nativeType):
             return 1 ^ function.hashValue ^ keyPath.hashValue ^ alias.hashValue ^ nativeType.hashValue
+            
+        case ._Identity(let alias, let nativeType):
+            return 3 ^ alias.hashValue ^ nativeType.hashValue
         }
     }
     
@@ -238,7 +262,8 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
     // MARK: Internal
     
     case _Attribute(KeyPath)
-    case _Aggregate(function: String, KeyPath, As: String, nativeType: NSAttributeType)
+    case _Aggregate(function: String, keyPath: KeyPath, alias: String, nativeType: NSAttributeType)
+    case _Identity(alias: String, nativeType: NSAttributeType)
 }
 
 
@@ -259,6 +284,9 @@ public func == (lhs: SelectTerm, rhs: SelectTerm) -> Bool {
             && alias1 == alias2
             && nativeType1 == nativeType2
         
+    case (._Identity(let alias1, let nativeType1), ._Identity(let alias2, let nativeType2)):
+        return alias1 == alias2 && nativeType1 == nativeType2
+        
     default:
         return false
     }
@@ -349,6 +377,14 @@ public struct Select<T: SelectResultType>: Hashable {
     internal let selectTerms: [SelectTerm]
 }
 
+public extension Select where T: NSManagedObjectID {
+    
+    public init() {
+        
+        self.init(.ObjectID())
+    }
+}
+
 
 // MARK: - Select: Equatable
 
@@ -710,6 +746,21 @@ internal extension CollectionType where Generator.Element == SelectTerm {
                         message: "The attribute \"\(keyPath)\" does not exist in entity \(typeName(entityDescription.managedObjectClassName)) and will be ignored by \(typeName(owner)) query clause."
                     )
                 }
+                
+            case ._Identity(let alias, let nativeType):
+                let expressionDescription = NSExpressionDescription()
+                expressionDescription.name = alias
+                if nativeType == .UndefinedAttributeType {
+                    
+                    expressionDescription.expressionResultType = .ObjectIDAttributeType
+                }
+                else {
+                    
+                    expressionDescription.expressionResultType = nativeType
+                }
+                expressionDescription.expression = NSExpression.expressionForEvaluatedObject()
+                
+                propertiesToFetch.append(expressionDescription)
             }
         }
         
@@ -725,6 +776,9 @@ internal extension CollectionType where Generator.Element == SelectTerm {
             
         case ._Aggregate(_, _, let alias, _):
             return alias
+            
+        case ._Identity(let alias, _):
+            return alias
         }
     }
 }

Sources/ObjectiveC/CSSelect.swift

@@ -131,6 +131,32 @@ public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType {
         return self.init(.Sum(keyPath, As: alias))
     }
     
+    /**
+     Provides a `CSSelectTerm` to a `CSSelect` clause for querying the `NSManagedObjectID`.
+     ```
+     NSManagedObjectID *objectID = [CSCoreStore
+         queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
+         select:[CSSelect objectIDForTerm:[CSSelectTerm objectIDAs:nil]]
+         fetchClauses:@[[CSWhere keyPath:@"employeeID" isEqualTo: @1111]]];
+     
+     let objectID = CoreStore.queryValue(
+     From(MyPersonEntity),
+     Select<NSManagedObjectID>(.ObjectID()),
+     Where("employeeID", isEqualTo: 1111)
+     )
+     ```
+     - parameter keyPath: the attribute name
+     - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "objecID" is used
+     - returns: a `SelectTerm` to a `Select` clause for querying the sum value for an attribute
+     */
+    public static func objectIDAs(alias: KeyPath? = nil) -> SelectTerm {
+        
+        return ._Identity(
+            alias: alias ?? "objectID",
+            nativeType: .ObjectIDAttributeType
+        )
+    }
+
     
     
     // MARK: NSObject
@@ -262,15 +288,15 @@ public final class CSSelect: NSObject {
      ```
      NSManagedObjectID *objectIDForOldest = [CSCoreStore
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
-         select:[CSSelect managedObjectIDForTerm:[CSSelectTerm attribute:@"age" as:nil]]
+         select:[CSSelect objectID]
          fetchClauses:@[[CSWhere keyPath:@"employeeID" isEqualTo: @1111]]];
      ```
      - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query
      - returns: a `CSSelect` clause for querying an entity attribute
      */
-    public static func managedObjectIDForTerm(term: CSSelectTerm) -> CSSelect {
+    public static func objectID() -> CSSelect {
         
-        return self.init(Select<NSManagedObjectID>(term.bridgeToSwift))
+        return self.init(Select<NSManagedObjectID>(.ObjectID()))
     }
     
     /**