nano-store 0.3.13 → 0.3.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. data/.rvmrc +1 -1
  2. data/Rakefile +1 -1
  3. data/lib/nano_store.rb +1 -1
  4. data/lib/nano_store/finder.rb +26 -9
  5. data/lib/nano_store/version.rb +1 -1
  6. data/nano-store.gemspec +2 -2
  7. data/spec/finder_spec.rb +29 -12
  8. data/vendor/Podfile.lock +8 -2
  9. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoBag.h +312 -0
  10. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoBag_Private.h +37 -0
  11. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoEngine.h +542 -0
  12. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoEngine_Private.h +69 -0
  13. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoExpression.h +125 -0
  14. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoExpression_Private.h +35 -0
  15. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoGlobals.h +323 -0
  16. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoGlobals_Private.h +99 -0
  17. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoObject.h +323 -0
  18. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoObjectProtocol.h +119 -0
  19. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoObject_Private.h +35 -0
  20. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoPredicate.h +123 -0
  21. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoPredicate_Private.h +35 -0
  22. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoResult.h +137 -0
  23. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoResult_Private.h +43 -0
  24. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoSearch.h +383 -0
  25. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoSearch_Private.h +48 -0
  26. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoSortDescriptor.h +124 -0
  27. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoStore.h +475 -0
  28. data/vendor/Pods/BuildHeaders/NanoStore/NSFNanoStore_Private.h +57 -0
  29. data/vendor/Pods/BuildHeaders/NanoStore/NanoStore.h +463 -0
  30. data/vendor/Pods/BuildHeaders/NanoStore/NanoStore_Private.h +37 -0
  31. data/vendor/Pods/Headers/NanoStore/NSFNanoObject.h +25 -0
  32. data/vendor/Pods/NanoStore/Classes/Public/NSFNanoObject.h +25 -0
  33. data/vendor/Pods/NanoStore/Classes/Public/NSFNanoObject.m +53 -28
  34. data/vendor/Pods/NanoStore/README.md +5 -1
  35. data/vendor/Pods/Pods.bridgesupport +635 -621
  36. data/vendor/Pods/Pods.xcconfig +4 -1
  37. metadata +36 -8
@@ -0,0 +1,35 @@
1
+ /*
2
+ NSFNanoObject.h
3
+ NanoStore
4
+
5
+ Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
6
+
7
+ Redistribution and use in source and binary forms, with or without modification, are permitted
8
+ provided that the following conditions are met:
9
+
10
+ * Redistributions of source code must retain the above copyright notice, this list of conditions
11
+ and the following disclaimer.
12
+ * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
13
+ and the following disclaimer in the documentation and/or other materials provided with the distribution.
14
+ * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
15
+ products derived from this software without specific prior written permission.
16
+
17
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
18
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
19
+ PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
20
+ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
23
+ OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24
+ SUCH DAMAGE.
25
+ */
26
+
27
+ #import "NSFNanoObject.h"
28
+
29
+ /** \cond */
30
+
31
+ @interface NSFNanoObject (Private)
32
+ - (void)_setOriginalClassString:(NSString *)theClassString;
33
+ @end
34
+
35
+ /** \endcond */
@@ -0,0 +1,123 @@
1
+ /*
2
+ NSFNanoPredicate.h
3
+ NanoStore
4
+
5
+ Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
6
+
7
+ Redistribution and use in source and binary forms, with or without modification, are permitted
8
+ provided that the following conditions are met:
9
+
10
+ * Redistributions of source code must retain the above copyright notice, this list of conditions
11
+ and the following disclaimer.
12
+ * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
13
+ and the following disclaimer in the documentation and/or other materials provided with the distribution.
14
+ * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
15
+ products derived from this software without specific prior written permission.
16
+
17
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
18
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
19
+ PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
20
+ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
23
+ OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24
+ SUCH DAMAGE.
25
+ */
26
+
27
+ /*! @file NSFNanoPredicate.h
28
+ @brief A predicate is an element of an expression used to perform complex queries.
29
+ */
30
+
31
+ /** @class NSFNanoPredicate
32
+ * A predicate is an element of an expression used to perform complex queries.
33
+ *
34
+ * @note
35
+ * A predicate must be added to a NSFNanoExpression.
36
+ *
37
+ * @details <b>Example:</b>
38
+ @code
39
+ // Instantiate a NanoStore and open it
40
+ NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
41
+
42
+ // Add some data to the document store
43
+ NSDictionary *info = ...;
44
+ NSFNanoObject *object = [NSFNanoObject nanoObjectWithDictionary:info];
45
+ [nanoStore addObject:object error:nil];
46
+
47
+ // Prepare the expression
48
+ NSFNanoPredicate *attribute = [NSFNanoPredicate predicateWithColumn:NSFAttributeColumn matching:NSFEqualTo value:@"FirstName"];
49
+ NSFNanoPredicate *value = [NSFNanoPredicate predicateWithColumn:NSFValueColumn matching:NSFEqualTo value:@"Hobbes"];
50
+ NSFNanoExpression *expression = [NSFNanoExpression expressionWithPredicate:predicateAttribute];
51
+ [expression addPredicate:predicateValue withOperator:NSFAnd];
52
+
53
+ // Setup the search with the document store and a given expression
54
+ NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
55
+ [search setExpressions:[NSArray arrayWithObject:expression]];
56
+
57
+ // Obtain the matching objects
58
+ NSDictionary *searchResults = [search searchObjectsWithReturnType:NSFReturnObjects error:nil];
59
+
60
+ // Close the document store
61
+ [nanoStore closeWithError:nil];
62
+ @endcode
63
+ *
64
+ * @see \link NSFNanoExpression::expressionWithPredicate: + (NSFNanoExpression*)expressionWithPredicate:(NSFNanoPredicate *)thePredicate \endlink
65
+ * @see \link NSFNanoExpression::initWithPredicate: - (id)initWithPredicate:(NSFNanoPredicate *)thePredicate \endlink
66
+ * @see \link NSFNanoExpression::addPredicate:withOperator: - (void)addPredicate:(NSFNanoPredicate *)thePredicate withOperator:(NSFOperator)theOperator \endlink
67
+ */
68
+
69
+ #import <Foundation/Foundation.h>
70
+
71
+ #import "NSFNanoGlobals.h"
72
+
73
+ @interface NSFNanoPredicate : NSObject
74
+
75
+ /** * The type of column being referenced. */
76
+ @property (nonatomic, assign, readonly) NSFTableColumnType column;
77
+ /** * The comparison operator to be used. */
78
+ @property (nonatomic, assign, readonly) NSFMatchType match;
79
+ /** * The value to be used for comparison. */
80
+ @property (nonatomic, copy, readonly) NSString *value;
81
+
82
+ /** @name Creating and Initializing a Predicate
83
+ */
84
+
85
+ //@{
86
+
87
+ /** * Creates and returns a predicate.
88
+ * @param theType is the column type. Can be \link Globals::NSFKeyColumn NSFKeyColumn \endlink, \link Globals::NSFAttributeColumn NSFAttributeColumn \endlink or \link Globals::NSFValueColumn NSFValueColumn \endlink.
89
+ * @param theMatch is the match operator.
90
+ * @param theValue is the value.
91
+ * @return A predicate which can be used in an NSFNanoExpression.
92
+ * @see \link initWithColumn:matching:value: - (id)initWithColumn:(NSFTableColumnType)theType matching:(NSFMatchType)theMatch value:(NSString *)theValue \endlink
93
+ */
94
+
95
+ + (NSFNanoPredicate*)predicateWithColumn:(NSFTableColumnType)theType matching:(NSFMatchType)theMatch value:(NSString *)theValue;
96
+
97
+ /** * Initializes a newly allocated predicate.
98
+ * @param theType is the column type. Can be \link Globals::NSFKeyColumn NSFKeyColumn \endlink, \link Globals::NSFAttributeColumn NSFAttributeColumn \endlink or \link Globals::NSFValueColumn NSFValueColumn \endlink.
99
+ * @param theMatch is the match operator.
100
+ * @param theValue is the value.
101
+ * @return A predicate which can be used in an NSFNanoExpression.
102
+ * @see \link predicateWithColumn:matching:value: + (NSFNanoPredicate*)predicateWithColumn:(NSFTableColumnType)theType matching:(NSFMatchType)theMatch value:(NSString *)theValue \endlink
103
+ */
104
+
105
+ - (id)initWithColumn:(NSFTableColumnType)theType matching:(NSFMatchType)theMatch value:(NSString *)theValue;
106
+
107
+ //@}
108
+
109
+ /** @name Miscellaneous
110
+ */
111
+
112
+ //@{
113
+
114
+ /** * Returns a string representation of the predicate.
115
+ * @note Check properties column, match and value to find out the current state of the predicate.
116
+ * @see \link description - (NSString *)description \endlink
117
+ */
118
+
119
+ - (NSString *)description;
120
+
121
+ //@}
122
+
123
+ @end
@@ -0,0 +1,35 @@
1
+ /*
2
+ NSFNanoSearch_Private.h
3
+ NanoStore
4
+
5
+ Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
6
+
7
+ Redistribution and use in source and binary forms, with or without modification, are permitted
8
+ provided that the following conditions are met:
9
+
10
+ * Redistributions of source code must retain the above copyright notice, this list of conditions
11
+ and the following disclaimer.
12
+ * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
13
+ and the following disclaimer in the documentation and/or other materials provided with the distribution.
14
+ * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
15
+ products derived from this software without specific prior written permission.
16
+
17
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
18
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
19
+ PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
20
+ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
23
+ OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24
+ SUCH DAMAGE.
25
+ */
26
+
27
+ #import "NanoStore.h"
28
+
29
+ /** \cond */
30
+
31
+ @interface NSFNanoPredicate (Private)
32
+ // Just a placeholder.
33
+ @end
34
+
35
+ /** \endcond */
@@ -0,0 +1,137 @@
1
+ /*
2
+ NSFNanoResult.h
3
+ NanoStore
4
+
5
+ Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
6
+
7
+ Redistribution and use in source and binary forms, with or without modification, are permitted
8
+ provided that the following conditions are met:
9
+
10
+ * Redistributions of source code must retain the above copyright notice, this list of conditions
11
+ and the following disclaimer.
12
+ * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
13
+ and the following disclaimer in the documentation and/or other materials provided with the distribution.
14
+ * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
15
+ products derived from this software without specific prior written permission.
16
+
17
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
18
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
19
+ PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
20
+ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
23
+ OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24
+ SUCH DAMAGE.
25
+ */
26
+
27
+ /*! @file NSFNanoResult.h
28
+ @brief A unit that describes the result of a search.
29
+ */
30
+
31
+ /** @class NSFNanoResult
32
+ * A unit that describes the result of a search.
33
+ *
34
+ * @note
35
+ * The NanoResult is the object representation of a SQL result set. From it, you can obtain the number of rows, the column names and their
36
+ * associated values.
37
+ *
38
+ * @par
39
+ * After obtaining a NanoResult, it's always a good idea to check whether the <i>error</i> property is nil. If so, the result can be assumed to be
40
+ * correct. Otherwise, <i>error</i> will point to the main cause of failure.
41
+ *
42
+ * @details <b>Example:</b>
43
+ @code
44
+ // Instantiate a NanoStore and open it
45
+ NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
46
+
47
+ // Add some data to the document store
48
+ NSDictionary *info = ...;
49
+ NSFNanoBag *bag = [NSFNanoBag bag];
50
+ NSFNanoObject *obj1 = [NSFNanoObject nanoObjectWithDictionary:info];
51
+ NSFNanoObject *obj2 = [NSFNanoObject nanoObjectWithDictionary:info];
52
+ [nanoStore addObjectsFromArray:[NSArray arrayWithObjects:obj1, obj2, nil] error:nil];
53
+
54
+ // Instantiate a search and execute the SQL statement
55
+ NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
56
+ NSFNanoResult *result = [search executeSQL:@"SELECT COUNT(*) FROM NSFKEYS"];
57
+
58
+ // Obtain the result (given as an NSString)
59
+ NSString *value = [result firstValue];
60
+
61
+ // Close the document store
62
+ [nanoStore closeWithError:nil];
63
+ @endcode
64
+ */
65
+
66
+ #import <Foundation/Foundation.h>
67
+
68
+ @class NSFNanoStore;
69
+
70
+ @interface NSFNanoResult : NSObject
71
+
72
+ /** * Number of rows contained in the result set. */
73
+ @property (nonatomic, assign, readonly) NSUInteger numberOfRows;
74
+ /** * A reference to the error encountered while processing the request, otherwise nil if the request was successful. */
75
+ @property (nonatomic, strong, readonly) NSError *error;
76
+
77
+ /** @name Accessors
78
+ */
79
+
80
+ //@{
81
+
82
+ /** * Returns a new array containing the columns.
83
+ * @returns An array with the columns retrieved from the result set.
84
+ */
85
+
86
+ - (NSArray *)columns;
87
+
88
+ /** * Returns a new array containing the values for a given column.
89
+ * @param theIndex is the index of the value in the result set.
90
+ * @param theColumn is the name of the column in the result set.
91
+ * @returns An array with the values associated with a given column.
92
+ * @throws NSRangeException is thrown if the index is out of bounds.
93
+ */
94
+
95
+ - (NSString *)valueAtIndex:(NSUInteger)theIndex forColumn:(NSString *)theColumn;
96
+
97
+ /** * Returns a new array containing the values for a given column.
98
+ * @param theColumn is the name of the column in the result set.
99
+ * @returns An array with the values associated with a given column.
100
+ */
101
+
102
+ - (NSArray *)valuesForColumn:(NSString *)theColumn;
103
+
104
+ /** * Returns the first value.
105
+ * @returns The value of the first element from the result set.
106
+ */
107
+
108
+ - (NSString *)firstValue;
109
+
110
+ //@}
111
+
112
+ /** @name Exporting the Results to a File
113
+ */
114
+
115
+ //@{
116
+
117
+ /** * Saves the result to a file.
118
+ * @param thePath is the location where the result will be saved to a file.
119
+ */
120
+
121
+ - (void)writeToFile:(NSString *)thePath;
122
+
123
+ //@}
124
+
125
+ /** @name Miscellaneous
126
+ */
127
+
128
+ //@{
129
+
130
+ /** * Returns a string representation of the result.
131
+ */
132
+
133
+ - (NSString *)description;
134
+
135
+ //@}
136
+
137
+ @end
@@ -0,0 +1,43 @@
1
+ /*
2
+ NSFNanoResult_Private.h
3
+ NanoStore
4
+
5
+ Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
6
+
7
+ Redistribution and use in source and binary forms, with or without modification, are permitted
8
+ provided that the following conditions are met:
9
+
10
+ * Redistributions of source code must retain the above copyright notice, this list of conditions
11
+ and the following disclaimer.
12
+ * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
13
+ and the following disclaimer in the documentation and/or other materials provided with the distribution.
14
+ * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
15
+ products derived from this software without specific prior written permission.
16
+
17
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
18
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
19
+ PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
20
+ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
23
+ OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24
+ SUCH DAMAGE.
25
+ */
26
+
27
+ #import "NSFNanoResult.h"
28
+
29
+ /** \cond */
30
+
31
+ @interface NSFNanoResult (Private)
32
+ + (NSFNanoResult *)_resultWithDictionary:(NSDictionary *)results;
33
+ + (NSFNanoResult *)_resultWithError:(NSError *)error;
34
+
35
+ - (id)_initWithDictionary:(NSDictionary *)results;
36
+ - (id)_initWithError:(NSError *)error;
37
+
38
+ - (void)_setError:(NSError *)error;
39
+ - (void)_reset;
40
+ - (void)_calculateNumberOfRows;
41
+ @end
42
+
43
+ /** \endcond */
@@ -0,0 +1,383 @@
1
+ /*
2
+ NSFNanoSearch.h
3
+ NanoStore
4
+
5
+ Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
6
+
7
+ Redistribution and use in source and binary forms, with or without modification, are permitted
8
+ provided that the following conditions are met:
9
+
10
+ * Redistributions of source code must retain the above copyright notice, this list of conditions
11
+ and the following disclaimer.
12
+ * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
13
+ and the following disclaimer in the documentation and/or other materials provided with the distribution.
14
+ * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
15
+ products derived from this software without specific prior written permission.
16
+
17
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
18
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
19
+ PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
20
+ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
23
+ OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24
+ SUCH DAMAGE.
25
+ */
26
+
27
+ /*! @file NSFNanoSearch.h
28
+ @brief A unit that provides an API to retrieve data from the document store.
29
+ */
30
+
31
+ /** @class NSFNanoSearch
32
+ * A unit that provides an API to retrieve data from the document store.
33
+ *
34
+ * The search can be conducted in two ways: programatically via setters or by providing a SQL statement. In both cases,
35
+ * it's necessary to indicate which object type should be returned. The type \link Globals::NSFReturnType NSFReturnType \endlink provides two options: \link Globals::NSFReturnObjects NSFReturnObjects \endlink and \link Globals::NSFReturnKeys NSFReturnKeys \endlink.
36
+ *
37
+ * - \link Globals::NSFReturnObjects NSFReturnObjects \endlink will return a dictionary with the key of the NanoObject (key) and the NanoObject itself (value).
38
+ * - \link Globals::NSFReturnKeys NSFReturnKeys \endlink will return an array of NanoObjects.
39
+ *
40
+ * @par <b>Some observations about retrieving data</b><br>
41
+ *
42
+ * Given the following data set:
43
+ *
44
+ * - Number of dictionaries: 3.956
45
+ * - Number of attributes: 593.862
46
+ *
47
+ * The table describing different timings to perform a simple value search (i.e. 'Barcelona') is included below, ordered from fastest to slowest:
48
+ *
49
+ *<table border="1" cellpadding="5">
50
+ *<tr>
51
+ *<th>Match type</th>
52
+ *<th>Seconds</th>
53
+ *</tr>
54
+ *<tr><td>Equal to</td><td>0.295</td></tr>
55
+ *<tr><td>Begins with</td><td>0.295</td></tr>
56
+ *<tr><td>Contains</td><td>1.295</td></tr>
57
+ *<tr><td>Contains (insensitive)</td><td>1.339</td></tr>
58
+ *<tr><td>Ends with (insensitive)</td><td>1.341</td></tr>
59
+ *<tr><td>Ends with</td><td>1.351</td></tr>
60
+ *<tr><td>Equal to (insensitive)</td><td>1.890</td></tr>
61
+ *<tr><td>Begins with (insensitive)</td><td>2.412</td></tr>
62
+ *<tr><td>Greater than</td><td>18.246</td></tr>
63
+ *<tr><td>Less than</td><td>27.677</td></tr>
64
+ *</table>
65
+
66
+ @section wherearetheobjects_sec Where are my objects?
67
+
68
+ While NSFNanoStore provides some convenience methods to obtain standard objects (such as objects of type NSFNanoBag), the bulk of the search mechanism is handled by NSFNanoSearch.
69
+ The steps involved to perform a search are quite simple:
70
+
71
+ - 1) Instantiate a search object
72
+ - 2) Configure the search via its accessors
73
+ - 3) Obtain the results specifying whether objects or keys should be returned (*)
74
+
75
+ (*) Request objects if you're interested in the data. Otherwise, you should request keys if you need to feed the result to another method, such as NSFNanoStore
76
+ \link NSFNanoStore::removeObjectsWithKeysInArray:error: -(BOOL)removeObjectsWithKeysInArray:(NSArray *)theKeys error:(out NSError **)outError \endlink method.
77
+
78
+ @details <b>Example: finding all objects with the attribute 'LastName' and value 'Doe'.</b>
79
+ @code
80
+ NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
81
+
82
+ search.attribute = @"LastName";
83
+ search.match = NSFEqualTo;
84
+ search.value = @"Doe";
85
+
86
+ // Returns a dictionary with the UUID of the object (key) and the NanoObject (value).
87
+ NSDictionary *searchResults = [search searchObjectsWithReturnType:NSFReturnObjects error:nil];
88
+ @endcode
89
+
90
+ @details <b>Example: removing all objects with the attribute 'LastName' and value 'Doe'.</b>
91
+ @code
92
+ NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
93
+
94
+ search.attribute = @"LastName";
95
+ search.match = NSFEqualTo;
96
+ search.value = @"Doe";
97
+
98
+ // Returns an array of matching UUIDs
99
+ NSArray *matchingKeys = [search searchObjectsWithReturnType:NSFReturnKeys error:nil];
100
+
101
+ // Remove the NanoObjects matching the selected UUIDs
102
+ NSError *outError = nil;
103
+ if (YES == [nanoStore removeObjectsWithKeysInArray:matchingKeys error:&outError]) {
104
+ NSLog(@"The matching objects have been removed.");
105
+ } else {
106
+ NSLog(@"An error has occurred while removing the matching objects. Reason: %@", [outError localizedDescription]);
107
+ }
108
+ @endcode
109
+
110
+ Another cool feature is the possibility to invoke aggregated functions (count, avg, min, max and total) on the search results. Using the search snippet above,
111
+ calculating the average salary of all people with last name equal to 'Doe' is very easy.
112
+
113
+ @details <b>Example: calculating the average salary of all objects with the attribute 'LastName' and value 'Doe'.</b>
114
+ @code
115
+ NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
116
+
117
+ search.attribute = @"LastName";
118
+ search.match = NSFEqualTo;
119
+ search.value = @"Doe";
120
+
121
+ float averageSalary = [[search aggregateOperation:NSFAverage onAttribute:@"Salary"]floatValue];
122
+ @endcode
123
+
124
+ * @details <b>Example:</b>
125
+ @code
126
+ // Instantiate a NanoStore and open it
127
+ NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
128
+
129
+ // Generate a NanoObject with a dictionary and a key
130
+ NSString *key = @"ABC-123";
131
+ NSDictionary *info = ...;
132
+ NSFNanoObject *nanoObject = [NSFNanoObject nanoObjectWithDictionary:info];
133
+
134
+ // Add it to the document store
135
+ [nanoStore addObject:nanoObject error:nil];
136
+
137
+ // Instantiate a search and specify the attribute(s) we want to search for
138
+ NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
139
+ search.key = key;
140
+
141
+ // Perform the search and obtain the results
142
+ NSDictionary *searchResults = [search searchObjectsWithReturnType:NSFReturnObjects error:nil];
143
+
144
+ // Close the document store
145
+ [nanoStore closeWithError:nil];
146
+ @endcode
147
+ */
148
+
149
+ #import <Foundation/Foundation.h>
150
+
151
+ #import "NSFNanoGlobals.h"
152
+
153
+ @class NSFNanoStore, NSFNanoResult;
154
+
155
+ @interface NSFNanoSearch : NSObject
156
+
157
+ /** * The document store used for searching. */
158
+ @property (nonatomic, weak, readonly) NSFNanoStore *nanoStore;
159
+ /** * The set of attributes to be returned on matching objects. */
160
+ @property (nonatomic, strong, readwrite) NSArray *attributesToBeReturned;
161
+ /** * The key used for searching. */
162
+ @property (nonatomic, copy, readwrite) NSString *key;
163
+ /** * The attribute used for searching. */
164
+ @property (nonatomic, copy, readwrite) NSString *attribute;
165
+ /** * The value used for searching. */
166
+ @property (nonatomic, copy, readwrite) id value;
167
+ /** * The comparison operator used for searching. */
168
+ @property (nonatomic, assign, readwrite) NSFMatchType match;
169
+ /** * The list of NSFNanoExpression objects used for searching. */
170
+ @property (nonatomic, strong, readwrite) NSArray *expressions;
171
+ /** * If set to YES, specifying NSFReturnKeys applies the DISTINCT function and groups the values. */
172
+ @property (nonatomic, assign, readwrite) BOOL groupValues;
173
+ /** * The SQL statement used for searching. Set when executeSQL: is invoked. */
174
+ @property (nonatomic, copy, readonly) NSString *sql;
175
+ /** * The sort holds an array of one or more sort descriptors of type \link NSFNanoSortDescriptor NSFNanoSortDescriptor \endlink. */
176
+ @property (nonatomic, strong, readwrite) NSArray *sort;
177
+ /** * The filterClass allows to filter the results based on a specific object class. */
178
+ @property (nonatomic, strong, readwrite) NSString *filterClass;
179
+
180
+ /** @name Creating and Initializing a Search
181
+ */
182
+
183
+ //@{
184
+
185
+ /** * Creates and returns a search element for a given document store.
186
+ * @param theNanoStore the document store where the search will be performed. Must not be nil.
187
+ * @return An search element upon success, nil otherwise.
188
+ * @see \link initWithStore: - (id)initWithStore:(NSFNanoStore *)theNanoStore \endlink
189
+ */
190
+
191
+ + (NSFNanoSearch *)searchWithStore:(NSFNanoStore *)theNanoStore;
192
+
193
+ /** * Initializes a newly allocated search element for a given document store.
194
+ * @param theNanoStore the document store where the search will be performed. Must not be nil.
195
+ * @return An search element upon success, nil otherwise.
196
+ * @see \link searchWithStore: + (NSFNanoSearch *)searchWithStore:(NSFNanoStore *)theNanoStore \endlink
197
+ */
198
+
199
+ - (id)initWithStore:(NSFNanoStore *)theNanoStore;
200
+
201
+ //@}
202
+
203
+ /** @name Searching
204
+ */
205
+
206
+ //@{
207
+
208
+ /** * Performs a search using the values of the properties.
209
+ * @param theReturnType the type of object to be returned. Can be \link Globals::NSFReturnObjects NSFReturnObjects \endlink or \link Globals::NSFReturnKeys NSFReturnKeys \endlink.
210
+ * @param outError is used if an error occurs. May be NULL.
211
+ * @return An array is returned if: 1) the sort has been specified or 2) the return type is \link Globals::NSFReturnKeys NSFReturnKeys \endlink. Otherwise, a dictionary is returned.
212
+ * @note The sort descriptor will be ignored when returning requesting NSFReturnKeys.
213
+ * @see \link searchObjectsAdded:date:returnType:error: - (id)searchObjectsAdded:(NSFDateMatchType)theDateMatch date:(NSDate *)theDate returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
214
+ */
215
+
216
+ - (id)searchObjectsWithReturnType:(NSFReturnType)theReturnType error:(out NSError **)outError;
217
+
218
+ /** * Performs a search using the values of the properties before, on or after a given date.
219
+ * @param theDateMatch the type of date comparison. Can be \link Globals::NSFBeforeDate NSFBeforeDate \endlink, \link Globals::NSFOnDate NSFOnDate \endlink or \link Globals::NSFAfterDate NSFAfterDate \endlink.
220
+ * @param theDate the date to use as a pivot during the search.
221
+ * @param theReturnType the type of object to be returned. Can be \link Globals::NSFReturnObjects NSFReturnObjects \endlink or \link Globals::NSFReturnKeys NSFReturnKeys \endlink.
222
+ * @param outError is used if an error occurs. May be NULL.
223
+ * @return If theReturnType is \link Globals::NSFReturnObjects NSFReturnObjects \endlink, a dictionary is returned. Otherwise, an array is returned.
224
+ * @note The sort descriptor will be ignored when returning requesting NSFReturnKeys.
225
+ * @see \link searchObjectsWithReturnType:error: - (id)searchObjectsWithReturnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
226
+ */
227
+
228
+ - (id)searchObjectsAdded:(NSFDateMatchType)theDateMatch date:(NSDate *)theDate returnType:(NSFReturnType)theReturnType error:(out NSError **)outError;
229
+
230
+ /** * Returns the result of the aggregate function.
231
+ * @param theFunctionType is the function type to be applied.
232
+ * @param theAttribute is the attribute used in the function.
233
+ * @returns An NSNumber containing the result of the aggregate function.
234
+ * @details <b>Example:</b>
235
+ @code
236
+ * NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
237
+ *
238
+ * // Assume we have saved data to the document store
239
+ * ...
240
+ * ...
241
+ *
242
+ * // Get the average for the attribute named 'SomeNumber'
243
+ * NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
244
+ * NSNumber *result = [search aggregateOperation:NSFAverage onAttribute:@"SomeNumber"];
245
+ @endcode
246
+ @note The sort descriptor will be ignored when executing aggregate operations.
247
+ */
248
+
249
+ - (NSNumber *)aggregateOperation:(NSFAggregateFunctionType)theFunctionType onAttribute:(NSString *)theAttribute;
250
+
251
+ /** * Performs a search with a given SQL statement.
252
+ * @param theSQLStatement is the SQL statement to be executed. Must not be nil or an empty string.
253
+ * @param theReturnType the type of object to be returned. Can be \link Globals::NSFReturnObjects NSFReturnObjects \endlink or \link Globals::NSFReturnKeys NSFReturnKeys \endlink.
254
+ * @param outError is used if an error occurs. May be NULL.
255
+ * @return If theReturnType is \link Globals::NSFReturnObjects NSFReturnObjects \endlink, a dictionary is returned. Otherwise, an array is returned.
256
+ * @note
257
+ * Use this method when performing search on NanoObjects. If you need to perform more advanced SQL statements, you may want to use
258
+ * \link executeSQL: - (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement \endlink instead.
259
+ * @par
260
+ * The key difference between this method and \link executeSQL: - (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement \endlink is that this method performs
261
+ * a check to make sure the columns specified match the ones required by the \link Globals::NSFReturnType NSFReturnType \endlink type selected. If the column selection is wrong,
262
+ * NanoStore rewrites the query by specifying the right set of columns while honoring the rest of the query.
263
+ * @details <b>Example:</b>
264
+ * @code
265
+ * // Prepare a document store
266
+ * NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
267
+ *
268
+ * // Prepare some data and wrap it in a NanoObject
269
+ * NSString *key = @"ABC-123";
270
+ * NSDictionary *info = ...;
271
+ * NSFNanoObject *nanoObject = [NSFNanoObject nanoObjectWithDictionary:info];
272
+ *
273
+ * // Add it to the document store
274
+ * [nanoStore addObjectsFromArray:[NSArray arrayWithObject:nanoObject] error:nil];
275
+ *
276
+ * // Instantiate a search and specify the attribute(s) we want to search for
277
+ * NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
278
+ *
279
+ * // Perform the search
280
+ * // The query will be rewritten as @"SELECT NSFKey, NSFPlist, NSFObjectClass FROM NSFKeys"
281
+ * NSDictionary *results = [search executeSQL:@"SELECT foo, bar FROM NSFKeys" returnType:NSFReturnObjects error:nil];
282
+ * @endcode
283
+ * @note The sort descriptor will be ignored when executing custom SQL statements.
284
+ * @see \link executeSQL: - (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement \endlink
285
+ */
286
+
287
+ - (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError;
288
+
289
+ /** * Performs a search with a given SQL statement.
290
+ * @param theSQLStatement is the SQL statement to be executed. Must not be nil or an empty string.
291
+ * @return Returns a NSFNanoResult.
292
+ * @note
293
+ * Use this method when you need to perform more advanced SQL statements. If you just want to query NanoObjects using your own SQL statement,
294
+ * you may want to use \link executeSQL:returnType:error: - (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink instead.
295
+ * @par
296
+ * The key difference between this method and \link executeSQL:returnType:error: - (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
297
+ * is that this method doesn't perform any check at all. The SQL statement will be sent verbatim to SQLite.
298
+ * @details <b>Example:</b>
299
+ * @code
300
+ * // Prepare a document store
301
+ * NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
302
+ *
303
+ * // Prepare some data and wrap it in a NanoObject
304
+ * NSString *key = @"ABC-123";
305
+ * NSDictionary *info = ...;
306
+ * NSFNanoObject *nanoObject = [NSFNanoObject nanoObjectWithDictionary:info];
307
+ *
308
+ * // Add it to the document store
309
+ * [nanoStore addObjectsFromArray:[NSArray arrayWithObject:nanoObject] error:nil];
310
+ *
311
+ * // Instantiate a search and specify the attribute(s) we want to search for
312
+ * NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
313
+ *
314
+ * // Perform the search
315
+ * NSFNanoResult *result = [search executeSQL:@"SELECT COUNT(*) FROM NSFKEYS"];
316
+ * @endcode
317
+ * @see \link executeSQL:returnType:error: - (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
318
+ * @note The sort descriptor will be ignored when executing custom SQL statements.
319
+ */
320
+
321
+ - (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement;
322
+
323
+ /** * Performs an analysis of the given SQL statement.
324
+ * @param theSQLStatement is the SQL statement to be analyzed. Must not be nil or an empty string.
325
+ * @return Returns a NSFNanoResult.
326
+ * @note
327
+ * Returns the sequence of virtual machine instructions with high-level information about what indices would have been used if the SQL statement had
328
+ * been executed.
329
+ *
330
+ * @warning
331
+ * The analysis generated by this method is intended for interactive analysis and troubleshooting only. The details of the output format
332
+ * are subject to change from one release of SQLite to the next. Applications should not use this method in production code since the exact behavior
333
+ * is undocumented, unspecified, and variable.
334
+ *
335
+ * For additional information about SQLite's Virtual Machine Opcodes, see http://www.sqlite.org/opcode.html
336
+ *
337
+ * The tutorial Virtual Database Engine of SQLite is available here: http://www.sqlite.org/vdbe.html
338
+ *
339
+ * @details <b>Example:</b>
340
+ * @code
341
+ * // Prepare a document store
342
+ * NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
343
+ *
344
+ * // Instantiate a search object
345
+ * NSFNanoSearch *search = [NSFNanoSearch searchWithStore:nanoStore];
346
+ *
347
+ * // Perform the analysis
348
+ * NSFNanoResult *results = [search explainSQL:@"SELECT * FROM NSFValues"];
349
+ * @endcode
350
+ * @see \link executeSQL: - (NSFNanoResult *)executeSQL:(NSString *)theSQLStatement \endlink
351
+ * @see \link executeSQL:returnType:error: - (id)executeSQL:(NSString *)theSQLStatement returnType:(NSFReturnType)theReturnType error:(out NSError **)outError \endlink
352
+ */
353
+
354
+ - (NSFNanoResult *)explainSQL:(NSString *)theSQLStatement;
355
+
356
+ //@}
357
+
358
+ /** @name Resetting Values
359
+ */
360
+
361
+ //@{
362
+
363
+ /** * Resets the values to a know, default state.
364
+ * - key = nil;
365
+ * - attribute = nil;
366
+ * - value = nil;
367
+ * - match = NSFContains;
368
+ * - object type = NSFReturnObjects;
369
+ * - groupValues = NO;
370
+ * - attributesReturned = nil;
371
+ * - type returned = NSFReturnObjects;
372
+ * - sql = nil;
373
+ * - sort = nil;
374
+ *
375
+ * @note
376
+ * When invoked, it sets the values of search to its initial state. Resetting and performing a search will select all records.
377
+ */
378
+
379
+ - (void)reset;
380
+
381
+ //@}
382
+
383
+ @end