Adopt modern Obj-C nullability, generics matching NSXML API #66

KissXML/Additions/DDXMLElementAdditions.h

@@ -4,21 +4,23 @@
 // These methods are not part of the standard NSXML API.
 // But any developer working extensively with XML will likely appreciate them.
 
+NS_ASSUME_NONNULL_BEGIN
 @interface DDXMLElement (DDAdditions)
 
-+ (DDXMLElement *)elementWithName:(NSString *)name xmlns:(NSString *)ns;
++ (nullable DDXMLElement *)elementWithName:(NSString *)name xmlns:(NSString *)ns;
 
-- (DDXMLElement *)elementForName:(NSString *)name;
-- (DDXMLElement *)elementForName:(NSString *)name xmlns:(NSString *)xmlns;
+- (nullable DDXMLElement *)elementForName:(NSString *)name;
+- (nullable DDXMLElement *)elementForName:(NSString *)name xmlns:(NSString *)xmlns;
 
-- (NSString *)xmlns;
+- (nullable NSString *)xmlns;
 - (void)setXmlns:(NSString *)ns;
 
 - (NSString *)prettyXMLString;
 - (NSString *)compactXMLString;
 
 - (void)addAttributeWithName:(NSString *)name stringValue:(NSString *)string;
 
-- (NSDictionary *)attributesAsDictionary;
+- (NSDictionary<NSString*,NSString*> *)attributesAsDictionary;
 
 @end
+NS_ASSUME_NONNULL_END

KissXML/Categories/NSString+DDXML.h

@@ -3,6 +3,7 @@
 // We redefine xmlChar to avoid a non-modular include
 typedef unsigned char xmlChar;
 
+NS_ASSUME_NONNULL_BEGIN
 @interface NSString (DDXML)
 
 /**
@@ -13,3 +14,4 @@ typedef unsigned char xmlChar;
 - (NSString *)stringByTrimming;
 
 @end
+NS_ASSUME_NONNULL_END

KissXML/DDXMLDocument.h

@@ -28,14 +28,15 @@ enum {
 };
 typedef NSUInteger DDXMLDocumentContentKind;
 
+NS_ASSUME_NONNULL_BEGIN
 @interface DDXMLDocument : DDXMLNode
 {
 }
 
-- (id)initWithXMLString:(NSString *)string options:(NSUInteger)mask error:(NSError **)error;
-//- (id)initWithContentsOfURL:(NSURL *)url options:(NSUInteger)mask error:(NSError **)error;
-- (id)initWithData:(NSData *)data options:(NSUInteger)mask error:(NSError **)error;
-//- (id)initWithRootElement:(DDXMLElement *)element;
+- (nullable instancetype)initWithXMLString:(NSString *)string options:(NSUInteger)mask error:(NSError **)error;
+//- (instancetype)initWithContentsOfURL:(NSURL *)url options:(NSUInteger)mask error:(NSError **)error;
+- (nullable instancetype)initWithData:(NSData *)data options:(NSUInteger)mask error:(NSError **)error;
+//- (instancetype)initWithRootElement:(DDXMLElement *)element;
 
 //+ (Class)replacementClassForClass:(Class)cls;
 
@@ -58,7 +59,7 @@ typedef NSUInteger DDXMLDocumentContentKind;
 //- (DDXMLDTD *)DTD;
 
 //- (void)setRootElement:(DDXMLNode *)root;
-- (DDXMLElement *)rootElement;
+- (nullable DDXMLElement *)rootElement;
 
 //- (void)insertChild:(DDXMLNode *)child atIndex:(NSUInteger)index;
 
@@ -75,10 +76,11 @@ typedef NSUInteger DDXMLDocumentContentKind;
 - (NSData *)XMLData;
 - (NSData *)XMLDataWithOptions:(NSUInteger)options;
 
-//- (id)objectByApplyingXSLT:(NSData *)xslt arguments:(NSDictionary *)arguments error:(NSError **)error;
-//- (id)objectByApplyingXSLTString:(NSString *)xslt arguments:(NSDictionary *)arguments error:(NSError **)error;
-//- (id)objectByApplyingXSLTAtURL:(NSURL *)xsltURL arguments:(NSDictionary *)argument error:(NSError **)error;
+//- (instancetype)objectByApplyingXSLT:(NSData *)xslt arguments:(NSDictionary *)arguments error:(NSError **)error;
+//- (instancetype)objectByApplyingXSLTString:(NSString *)xslt arguments:(NSDictionary *)arguments error:(NSError **)error;
+//- (instancetype)objectByApplyingXSLTAtURL:(NSURL *)xsltURL arguments:(NSDictionary *)argument error:(NSError **)error;
 
 //- (BOOL)validateAndReturnError:(NSError **)error;
 
 @end
+NS_ASSUME_NONNULL_END

KissXML/DDXMLDocument.m

@@ -29,26 +29,26 @@ @implementation DDXMLDocument
  * Returns a DDXML wrapper object for the given primitive node.
  * The given node MUST be non-NULL and of the proper type.
 **/
-+ (id)nodeWithDocPrimitive:(xmlDocPtr)doc owner:(DDXMLNode *)owner
++ (instancetype)nodeWithDocPrimitive:(xmlDocPtr)doc owner:(DDXMLNode *)owner
 {
 	return [[DDXMLDocument alloc] initWithDocPrimitive:doc owner:owner];
 }
 
-- (id)initWithDocPrimitive:(xmlDocPtr)doc owner:(DDXMLNode *)inOwner
+- (instancetype)initWithDocPrimitive:(xmlDocPtr)doc owner:(DDXMLNode *)inOwner
 {
 	self = [super initWithPrimitive:(xmlKindPtr)doc owner:inOwner];
 	return self;
 }
 
-+ (id)nodeWithPrimitive:(xmlKindPtr)kindPtr owner:(DDXMLNode *)owner
++ (instancetype)nodeWithPrimitive:(xmlKindPtr)kindPtr owner:(DDXMLNode *)owner
 {
 	// Promote initializers which use proper parameter types to enable compiler to catch more mistakes
 	NSAssert(NO, @"Use nodeWithDocPrimitive:owner:");
 
 	return nil;
 }
 
-- (id)initWithPrimitive:(xmlKindPtr)kindPtr owner:(DDXMLNode *)inOwner
+- (instancetype)initWithPrimitive:(xmlKindPtr)kindPtr owner:(DDXMLNode *)inOwner
 {
 	// Promote initializers which use proper parameter types to enable compiler to catch more mistakes.
 	NSAssert(NO, @"Use initWithDocPrimitive:owner:");
@@ -62,7 +62,7 @@ - (id)initWithPrimitive:(xmlKindPtr)kindPtr owner:(DDXMLNode *)inOwner
  * Returns an initialized DDXMLDocument object, or nil if initialization fails
  * because of parsing errors or other reasons.
 **/
-- (id)initWithXMLString:(NSString *)string options:(NSUInteger)mask error:(NSError **)error
+- (instancetype)initWithXMLString:(NSString *)string options:(NSUInteger)mask error:(NSError **)error
 {
 	return [self initWithData:[string dataUsingEncoding:NSUTF8StringEncoding]
 	                  options:mask
@@ -75,7 +75,7 @@ - (id)initWithXMLString:(NSString *)string options:(NSUInteger)mask error:(NSErr
  * Returns an initialized DDXMLDocument object, or nil if initialization fails
  * because of parsing errors or other reasons.
 **/
-- (id)initWithData:(NSData *)data options:(NSUInteger)mask error:(NSError **)error
+- (instancetype)initWithData:(NSData *)data options:(NSUInteger)mask error:(NSError **)error
 {
 	if (data == nil || [data length] == 0)
 	{

KissXML/DDXMLElement.h

@@ -19,48 +19,48 @@
  * https://github.com/robbiehanson/KissXML/wiki/Reference
 **/
 
+NS_ASSUME_NONNULL_BEGIN
 @interface DDXMLElement : DDXMLNode
 {
 }
 
-- (id)initWithName:(NSString *)name;
-- (id)initWithName:(NSString *)name URI:(NSString *)URI;
-- (id)initWithName:(NSString *)name stringValue:(NSString *)string;
-- (id)initWithXMLString:(NSString *)string error:(NSError **)error;
+- (instancetype)initWithName:(NSString *)name;
+- (instancetype)initWithName:(NSString *)name URI:(nullable NSString *)URI;
+- (instancetype)initWithName:(NSString *)name stringValue:(nullable NSString *)string;
+- (nullable instancetype)initWithXMLString:(NSString *)string error:(NSError **)error NS_DESIGNATED_INITIALIZER;
 
 #pragma mark --- Elements by name ---
 
-- (NSArray *)elementsForName:(NSString *)name;
-- (NSArray *)elementsForLocalName:(NSString *)localName URI:(NSString *)URI;
+- (NSArray<DDXMLElement *> *)elementsForName:(NSString *)name;
+- (NSArray<DDXMLElement *> *)elementsForLocalName:(NSString *)localName URI:(nullable NSString *)URI;
 
 #pragma mark --- Attributes ---
 
 - (void)addAttribute:(DDXMLNode *)attribute;
 - (void)removeAttributeForName:(NSString *)name;
-- (void)setAttributes:(NSArray *)attributes;
+@property (nullable, copy) NSArray<DDXMLNode *> *attributes;
 //- (void)setAttributesAsDictionary:(NSDictionary *)attributes;
-- (NSArray *)attributes;
-- (DDXMLNode *)attributeForName:(NSString *)name;
+- (nullable DDXMLNode *)attributeForName:(NSString *)name;
 //- (DDXMLNode *)attributeForLocalName:(NSString *)localName URI:(NSString *)URI;
 
 #pragma mark --- Namespaces ---
 
 - (void)addNamespace:(DDXMLNode *)aNamespace;
 - (void)removeNamespaceForPrefix:(NSString *)name;
-- (void)setNamespaces:(NSArray *)namespaces;
-- (NSArray *)namespaces;
-- (DDXMLNode *)namespaceForPrefix:(NSString *)prefix;
-- (DDXMLNode *)resolveNamespaceForName:(NSString *)name;
-- (NSString *)resolvePrefixForNamespaceURI:(NSString *)namespaceURI;
+@property (nullable, copy) NSArray<DDXMLNode *> *namespaces; //primitive
+- (nullable DDXMLNode *)namespaceForPrefix:(NSString *)prefix;
+- (nullable DDXMLNode *)resolveNamespaceForName:(NSString *)name;
+- (nullable NSString *)resolvePrefixForNamespaceURI:(NSString *)namespaceURI;
 
 #pragma mark --- Children ---
 
 - (void)insertChild:(DDXMLNode *)child atIndex:(NSUInteger)index;
 //- (void)insertChildren:(NSArray *)children atIndex:(NSUInteger)index;
 - (void)removeChildAtIndex:(NSUInteger)index;
-- (void)setChildren:(NSArray *)children;
+- (void)setChildren:(nullable NSArray<DDXMLNode *> *)children;
 - (void)addChild:(DDXMLNode *)child;
 //- (void)replaceChildAtIndex:(NSUInteger)index withNode:(DDXMLNode *)node;
 //- (void)normalizeAdjacentTextNodesPreservingCDATA:(BOOL)preserve;
 
 @end
+NS_ASSUME_NONNULL_END

KissXML/DDXMLElement.m

@@ -29,34 +29,34 @@ @implementation DDXMLElement
  * Returns a DDXML wrapper object for the given primitive node.
  * The given node MUST be non-NULL and of the proper type.
 **/
-+ (id)nodeWithElementPrimitive:(xmlNodePtr)node owner:(DDXMLNode *)owner
++ (instancetype)nodeWithElementPrimitive:(xmlNodePtr)node owner:(DDXMLNode *)owner
 {
 	return [[DDXMLElement alloc] initWithElementPrimitive:node owner:owner];
 }
 
-- (id)initWithElementPrimitive:(xmlNodePtr)node owner:(DDXMLNode *)inOwner
+- (instancetype)initWithElementPrimitive:(xmlNodePtr)node owner:(DDXMLNode *)inOwner
 {
 	self = [super initWithPrimitive:(xmlKindPtr)node owner:inOwner];
 	return self;
 }
 
-+ (id)nodeWithPrimitive:(xmlKindPtr)kindPtr owner:(DDXMLNode *)owner
++ (instancetype)nodeWithPrimitive:(xmlKindPtr)kindPtr owner:(DDXMLNode *)owner
 {
 	// Promote initializers which use proper parameter types to enable compiler to catch more mistakes
 	NSAssert(NO, @"Use nodeWithElementPrimitive:owner:");
 
 	return nil;
 }
 
-- (id)initWithPrimitive:(xmlKindPtr)kindPtr owner:(DDXMLNode *)inOwner
+- (instancetype)initWithPrimitive:(xmlKindPtr)kindPtr owner:(DDXMLNode *)inOwner
 {
 	// Promote initializers which use proper parameter types to enable compiler to catch more mistakes.
 	NSAssert(NO, @"Use initWithElementPrimitive:owner:");
 
 	return nil;
 }
 
-- (id)initWithName:(NSString *)name
+- (instancetype)initWithName:(NSString *)name
 {
 	// Note: Make every guarantee that genericPtr is not null
 
@@ -69,7 +69,7 @@ - (id)initWithName:(NSString *)name
 	return [self initWithElementPrimitive:node owner:nil];
 }
 
-- (id)initWithName:(NSString *)name URI:(NSString *)URI
+- (instancetype)initWithName:(NSString *)name URI:(NSString *)URI
 {
 	// Note: Make every guarantee that genericPtr is not null
 
@@ -85,7 +85,7 @@ - (id)initWithName:(NSString *)name URI:(NSString *)URI
 	return result;
 }
 
-- (id)initWithName:(NSString *)name stringValue:(NSString *)string
+- (instancetype)initWithName:(NSString *)name stringValue:(NSString *)string
 {
 	// Note: Make every guarantee that genericPtr is not null
 
@@ -101,7 +101,7 @@ - (id)initWithName:(NSString *)name stringValue:(NSString *)string
 	return result;
 }
 
-- (id)initWithXMLString:(NSString *)string error:(NSError **)error
+- (instancetype)initWithXMLString:(NSString *)string error:(NSError **)error
 {
 	DDXMLDocument *doc = [[DDXMLDocument alloc] initWithXMLString:string options:0 error:error];
 	if (doc == nil)

KissXML/DDXMLNode.h

@@ -45,24 +45,24 @@ enum {
 };
 
 
-
+NS_ASSUME_NONNULL_BEGIN
 @interface DDXMLNode : NSObject <NSCopying>
 
-//- (id)initWithKind:(DDXMLNodeKind)kind;
+//- (instancetype)initWithKind:(DDXMLNodeKind)kind;
 
-//- (id)initWithKind:(DDXMLNodeKind)kind options:(NSUInteger)options;
+//- (instancetype)initWithKind:(DDXMLNodeKind)kind options:(NSUInteger)options;
 
-//+ (id)document;
+//+ (instancetype)document;
 
-//+ (id)documentWithRootElement:(DDXMLElement *)element;
+//+ (instancetype)documentWithRootElement:(DDXMLElement *)element;
 
 + (id)elementWithName:(NSString *)name;
 
 + (id)elementWithName:(NSString *)name URI:(NSString *)URI;
 
 + (id)elementWithName:(NSString *)name stringValue:(NSString *)string;
 
-+ (id)elementWithName:(NSString *)name children:(NSArray *)children attributes:(NSArray *)attributes;
++ (id)elementWithName:(NSString *)name children:(nullable NSArray<DDXMLNode *> *)children attributes:(nullable NSArray<DDXMLNode *> *)attributes;
 
 + (id)attributeWithName:(NSString *)name stringValue:(NSString *)stringValue;
 
@@ -76,68 +76,66 @@ enum {
 
 + (id)textWithStringValue:(NSString *)stringValue;
 
-//+ (id)DTDNodeWithXMLString:(NSString *)string;
+//+ (instancetype)DTDNodeWithXMLString:(NSString *)string;
 
 #pragma mark --- Properties ---
 
 - (DDXMLNodeKind)kind;
 
-- (void)setName:(NSString *)name;
-- (NSString *)name;
+@property (nullable, copy) NSString *name; //primitive
 
 //- (void)setObjectValue:(id)value;
-//- (id)objectValue;
+//- (instancetype)objectValue;
 
-- (void)setStringValue:(NSString *)string;
+@property (nullable, copy) NSString *stringValue; //primitive
 //- (void)setStringValue:(NSString *)string resolvingEntities:(BOOL)resolve;
-- (NSString *)stringValue;
 
 #pragma mark --- Tree Navigation ---
 
 - (NSUInteger)index;
 
 - (NSUInteger)level;
 
-- (DDXMLDocument *)rootDocument;
+- (nullable DDXMLDocument *)rootDocument;
 
-- (DDXMLNode *)parent;
+- (nullable DDXMLNode *)parent;
 - (NSUInteger)childCount;
-- (NSArray *)children;
-- (DDXMLNode *)childAtIndex:(NSUInteger)index;
+- (nullable NSArray<DDXMLNode *> *)children;
+- (nullable DDXMLNode *)childAtIndex:(NSUInteger)index;
 
-- (DDXMLNode *)previousSibling;
-- (DDXMLNode *)nextSibling;
+- (nullable DDXMLNode *)previousSibling;
+- (nullable DDXMLNode *)nextSibling;
 
-- (DDXMLNode *)previousNode;
-- (DDXMLNode *)nextNode;
+- (nullable DDXMLNode *)previousNode;
+- (nullable DDXMLNode *)nextNode;
 
 - (void)detach;
 
-- (NSString *)XPath;
+- (nullable NSString *)XPath;
 
 #pragma mark --- QNames ---
 
-- (NSString *)localName;
-- (NSString *)prefix;
+- (nullable NSString *)localName;
+- (nullable NSString *)prefix;
 
-- (void)setURI:(NSString *)URI;
-- (NSString *)URI;
+@property (nullable, copy) NSString *URI; //primitive
 
 + (NSString *)localNameForName:(NSString *)name;
-+ (NSString *)prefixForName:(NSString *)name;
++ (nullable NSString *)prefixForName:(NSString *)name;
 //+ (DDXMLNode *)predefinedNamespaceForPrefix:(NSString *)name;
 
 #pragma mark --- Output ---
 
-- (NSString *)description;
-- (NSString *)XMLString;
-- (NSString *)XMLStringWithOptions:(NSUInteger)options;
+- (nonnull NSString *)description;
+- (nonnull NSString *)XMLString;
+- (nonnull NSString *)XMLStringWithOptions:(NSUInteger)options;
 //- (NSString *)canonicalXMLStringPreservingComments:(BOOL)comments;
 
 #pragma mark --- XPath/XQuery ---
 
-- (NSArray *)nodesForXPath:(NSString *)xpath error:(NSError **)error;
+- (nullable NSArray<__kindof DDXMLNode *> *)nodesForXPath:(NSString *)xpath error:(NSError **)error;
 //- (NSArray *)objectsForXQuery:(NSString *)xquery constants:(NSDictionary *)constants error:(NSError **)error;
 //- (NSArray *)objectsForXQuery:(NSString *)xquery error:(NSError **)error;
 
 @end
+NS_ASSUME_NONNULL_END