URL Query Parameter handling additions to KSURLComponents

KSFileUtilities.xcodeproj/project.pbxproj

@@ -16,6 +16,7 @@
 		27A90103165C003A00D23C4B /* nameprep.c in Sources */ = {isa = PBXBuildFile; fileRef = 27A90101165C003A00D23C4B /* nameprep.c */; };
 		27A90106165C005700D23C4B /* puny.c in Sources */ = {isa = PBXBuildFile; fileRef = 27A90104165C005600D23C4B /* puny.c */; };
 		27DA2577148E641100209E50 /* TestKSURLUtilities.m in Sources */ = {isa = PBXBuildFile; fileRef = 27DA2576148E641100209E50 /* TestKSURLUtilities.m */; };
+		27DC29041859BC2C0089D717 /* KSURLQuery.m in Sources */ = {isa = PBXBuildFile; fileRef = 27DC29031859BC2C0089D717 /* KSURLQuery.m */; };
 		27F0501C178829220019FC07 /* KSURLComponents.m in Sources */ = {isa = PBXBuildFile; fileRef = 27F0501B178829180019FC07 /* KSURLComponents.m */; };
 		27F0501E1788399E0019FC07 /* TestKSURLComponents.m in Sources */ = {isa = PBXBuildFile; fileRef = 27F0501D1788399E0019FC07 /* TestKSURLComponents.m */; };
 		27F86FBF164FBA9D003608CC /* KSEncodeURLString.m in Sources */ = {isa = PBXBuildFile; fileRef = 27F86FBE164FBA9D003608CC /* KSEncodeURLString.m */; };
@@ -50,6 +51,8 @@
 		27A90104165C005600D23C4B /* puny.c */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.c; name = puny.c; path = IFUnicodeURL/IDNSDK/puny.c; sourceTree = "<group>"; };
 		27A90105165C005700D23C4B /* puny.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = puny.h; path = IFUnicodeURL/IDNSDK/puny.h; sourceTree = "<group>"; };
 		27DA2576148E641100209E50 /* TestKSURLUtilities.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = TestKSURLUtilities.m; sourceTree = "<group>"; };
+		27DC29021859BC2C0089D717 /* KSURLQuery.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = KSURLQuery.h; sourceTree = SOURCE_ROOT; };
+		27DC29031859BC2C0089D717 /* KSURLQuery.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = KSURLQuery.m; sourceTree = SOURCE_ROOT; };
 		27F0501A178829180019FC07 /* KSURLComponents.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = KSURLComponents.h; sourceTree = SOURCE_ROOT; };
 		27F0501B178829180019FC07 /* KSURLComponents.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = KSURLComponents.m; sourceTree = SOURCE_ROOT; };
 		27F0501D1788399E0019FC07 /* TestKSURLComponents.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = TestKSURLComponents.m; sourceTree = "<group>"; };
@@ -124,6 +127,8 @@
 				27246F10165BF1D2001B638E /* IFUnicodeURL */,
 				27F0501A178829180019FC07 /* KSURLComponents.h */,
 				27F0501B178829180019FC07 /* KSURLComponents.m */,
+				27DC29021859BC2C0089D717 /* KSURLQuery.h */,
+				27DC29031859BC2C0089D717 /* KSURLQuery.m */,
 				27422A77180D609B00136F43 /* KSMailtoURLs.h */,
 				27422A78180D609B00136F43 /* KSMailtoURLs.m */,
 				27F86FBD164FBA9D003608CC /* KSEncodeURLString.h */,
@@ -296,6 +301,7 @@
 				EE43C85213898D7B008ABD16 /* KSWebLocation.m in Sources */,
 				EE43C85313898D7B008ABD16 /* KSWebLocationPasteboardUtilities.m in Sources */,
 				27F0501E1788399E0019FC07 /* TestKSURLComponents.m in Sources */,
+				27DC29041859BC2C0089D717 /* KSURLQuery.m in Sources */,
 				27F0501C178829220019FC07 /* KSURLComponents.m in Sources */,
 				EE43C85413898D7B008ABD16 /* KSWorkspaceUtilities.m in Sources */,
 				27DA2577148E641100209E50 /* TestKSURLUtilities.m in Sources */,

KSMailtoURLs.m

@@ -26,7 +26,7 @@
 
 #import "KSMailtoURLs.h"
 
-#import "KSURLQueryUtilities.h"
+#import "KSURLQuery.h"
 
 
 NSString *KSURLMailtoScheme = @"mailto";
@@ -52,7 +52,7 @@ + (NSURL *)ks_mailtoURLWithEmailAddress:(NSString *)address headerLines:(NSDicti
 
     if (headers)
     {
-        NSString *query = [self ks_queryWithParameters:headers];
+        NSString *query = [KSURLQuery encodeParameters:headers];
         if ([query length])
         {
             string = [string stringByAppendingFormat:@"?%@", query];
@@ -72,7 +72,7 @@ - (NSDictionary *)ks_mailHeaderLines;
     if (queryIndicatorRange.location != NSNotFound)
     {
         NSString *query = [urlString substringFromIndex:NSMaxRange(queryIndicatorRange)];
-        return [NSURL ks_parametersOfQuery:query];
+        return [KSURLQuery decodeString:query options:0];
     }
 
     return nil;

KSURLComponents.h

@@ -26,6 +26,7 @@
 
 #import <Foundation/Foundation.h>
 
+
 @interface KSURLComponents : NSObject <NSCopying>
 {
   @private
@@ -117,13 +118,12 @@
 @property (nonatomic, copy) NSString *query;
 @property (nonatomic, copy) NSString *fragment;
 
-// Getting these properties retains any percent encoding these components may have. Setting these properties is currently not supported as I am lazy and doing so is rarely useful. If you do have a use case, please send me a pull request or file an issue on GitHub.
+// Getting these properties retains any percent encoding these components may have. Setting most of these properties is currently not supported as I am lazy and doing so is rarely useful. If you do have a use case, please send me a pull request or file an issue on GitHub.
 @property (nonatomic, copy, readonly) NSString *percentEncodedUser;
 @property (nonatomic, copy, readonly) NSString *percentEncodedPassword;
 @property (nonatomic, copy, readonly) NSString *percentEncodedHost;
 @property (nonatomic, copy, readonly) NSString *percentEncodedPath;
-@property (nonatomic, copy, readonly) NSString *percentEncodedQuery;
+@property (nonatomic, copy) NSString *percentEncodedQuery;
 @property (nonatomic, copy, readonly) NSString *percentEncodedFragment;
 
-
 @end

KSURLComponents.m

@@ -32,7 +32,6 @@ @interface KSURLComponents ()
 @property (nonatomic, copy, readwrite) NSString *percentEncodedPassword;
 @property (nonatomic, copy, readwrite) NSString *percentEncodedHost;
 @property (nonatomic, copy, readwrite) NSString *percentEncodedPath;
-@property (nonatomic, copy, readwrite) NSString *percentEncodedQuery;
 @property (nonatomic, copy, readwrite) NSString *percentEncodedFragment;
 @end
 
@@ -447,6 +446,12 @@ - (void)setPath:(NSString *)path;
 }
 
 @synthesize percentEncodedQuery = _queryComponent;
+- (void)setPercentEncodedQuery:(NSString *)percentEncodedQuery;
+{
+    // FIXME: Check the query is valid
+    percentEncodedQuery = [percentEncodedQuery copy];
+    [_queryComponent release]; _queryComponent = percentEncodedQuery;
+}
 - (NSString *)query;
 {
     return [self.percentEncodedQuery stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding];

KSURLQuery.h

@@ -0,0 +1,119 @@
+//
+//  KSURLQuery.h
+//  KSFileUtilities
+//
+//  Created by Mike on 12/12/2013.
+//  Copyright (c) 2013 Karelia Software. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+
+typedef NS_OPTIONS(NSUInteger, KSURLQueryParameterDecodingOptions) {
+    KSURLQueryParameterDecodingPlusAsSpace = 1UL << 0,    // + characters are interpreted as spaces, rather than regular + symbols
+};
+
+
+@interface KSURLQuery : NSObject
+{
+  @private
+    NSString    *_percentEncodedString;
+}
+
+#pragma mark Convenience
++ (NSString *)encodeParameters:(NSDictionary *)parameters;
++ (NSDictionary *)decodeString:(NSString *)percentEncodedQuery options:(KSURLQueryParameterDecodingOptions)options;
++ (NSDictionary *)parametersFromURL:(NSURL *)url options:(KSURLQueryParameterDecodingOptions)options;
+
+
+#pragma mark Creating a KSURLQuery
++ (instancetype)queryWithURL:(NSURL *)url;
+- initWithPercentEncodedString:(NSString *)string;
+
+
+#pragma mark Decoding Parameters
+
+/**
+ Converts the query into a dictionary representation.
+
+ For example:
+
+ http://example.com?key=value&foo=bar
+
+ can be interpreted as:
+
+ @{ @"key" : @"value", @"foo" : @"bar" }
+
+ Keys and values are percent decoded according to `options`.
+
+ If you have a query which doesn't match `NSDictionary`'s design, drop down to
+ the primitive `-enumerateParametersWithOptions:usingBlock:` method instead.
+
+ @param options A mask that specifies options for parameter decoding.
+ @return `nil` if query doesn't neatly fit an `NSDictionary` representation
+ */
+- (NSDictionary *)parametersWithOptions:(KSURLQueryParameterDecodingOptions)options;
+
+/**
+ Enumerates the receiver's parameters, handling cases where an NSDictionary representation doesn't suffice.
+
+ * Parameters are reported in the order they appear in the URL
+ * Keys and values are percent decoded for your convenience
+ * Parameters without a value are reported as `nil`
+ * Duplicate parameters are correctly reported too
+
+ @param options A mask that specifies options for parameter decoding.
+ @param block A block called for each parameter of the query.
+ */
+- (void)enumerateParametersWithOptions:(KSURLQueryParameterDecodingOptions)options usingBlock:(void (^)(NSString *key, NSString *value, BOOL *stop))block __attribute((nonnull(2)));
+
+
+#pragma mark Encoding Parameters
+
+/**
+ Replaces any existing query by encoding the `parameters` dictionary.
+
+ For example:
+
+ @{ @"key" : @"value", @"foo" : @"bar" }
+
+ can be represented as:
+
+ http://example.com?key=value&foo=bar
+
+ See `-addParameter:value:` for full details on encoding of keys and values.
+
+ Parameters are encoded in alphabetical order (of keys) for consistency across
+ platforms and OS releases. If ordering is important to your use case, or you
+ particularly need to eke out a little more performance, use `-addParameter:value:`
+ directly instead.
+
+ @param parameters A dictionary to encode, whose keys and values are all strings.
+ */
+- (void)setParameters:(NSDictionary *)parameters;
+
+/**
+ Adds an extra parameter to end of the receiver.
+
+ Enables the query to be built up piece-by-piece. This can be especially useful
+ when the ordering of parameters is critical, and/or parameters appear more than
+ once.
+
+ Both the key and value are percent encoded.
+
+ `value` is sent a `-description` message to obtain a string representation
+ suitable for encoding, enabling objects like `NSNumber`s to be easily encoded,
+ as well as strings.
+ */
+- (void)addParameter:(NSString *)key value:(id <NSObject>)value __attribute((nonnull(1)));
+
+/**
+ @result The encoded representation of the receiver.
+
+ Generally you then pass the result of this method to `NSURLComponents.percentEncodedQuery`
+ (or `KSURLComponents`) to build up a full URL.
+ */
+@property(atomic, readonly, copy) NSString *percentEncodedString;
+
+
+@end