Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Added comments

  • Loading branch information...
commit 3c87422c21f32e97678a77c51846c7a9d0b63e31 1 parent d1ff5b9
arashpayan authored
Showing with 112 additions and 6 deletions.
  1. +6 −0 APAttribute.m
  2. +36 −4 APDocument.m
  3. +70 −2 APElement.m
View
6 APAttribute.m
@@ -26,10 +26,16 @@ @implementation APAttribute
@synthesize name;
@synthesize value;
+/*
+ Returns an APAttribute with the specified name and value.
+*/
+ (id)attributeWithName:(NSString*)aName value:(NSString*)aValue {
return [[[APAttribute alloc] initWithName:aName value:aValue] autorelease];
}
+/*
+ Initializes the receiver with a specified name and value
+*/
- (id)initWithName:(NSString*)aName value:(NSString*)aValue {
if (self = [super init])
{
View
40 APDocument.m
@@ -21,6 +21,13 @@
#import "APDocument.h"
#import "APElement.h"
+/*
+ You probably only need to care about this class if you want to make
+ changes to the way APXML builds APDocuments.
+
+ This class is used as the NSXMLParser delegate that's responsible for
+ building APDocuments.
+*/
@interface APXMLBuilder : NSObject
{
APElement *rootElement;
@@ -93,9 +100,9 @@ - (void)parser:(NSXMLParser *)parser foundCharacters:(NSString *)string {
[openElement appendValue:string];
}
-- (void)parser:(NSXMLParser *)parser foundIgnorableWhitespace:(NSString *)whitespaceString {
-}
-
+/*
+ Returns the root element of the document that was parsed in.
+*/
- (APElement*)rootElement {
return rootElement;
}
@@ -113,13 +120,24 @@ - (void) dealloc
-
+/*
+ DOM representation of an XML document
+*/
@implementation APDocument
+/*
+ Returns an APDocument representation of the specified xml. Should be used
+ if you want to read in some XML as a document and want to manipulate it as
+ such.
+*/
+ (id)documentWithXMLString:(NSString*)anXMLString {
return [[[APDocument alloc] initWithString:anXMLString] autorelease];
}
+/*
+ Initializes the document with a root element. This should be used
+ if you're creating a new document programmatically.
+*/
- (id)initWithRootElement:(APElement*)aRootElement {
if (self = [super init])
{
@@ -129,6 +147,9 @@ - (id)initWithRootElement:(APElement*)aRootElement {
return self;
}
+/*
+ Initializes the document with an XML string.
+*/
- (id)initWithString:(NSString*)anXMLString {
if (self = [super init])
{
@@ -146,10 +167,17 @@ - (id)initWithString:(NSString*)anXMLString {
return self;
}
+/*
+ Returns the document's root element
+*/
- (APElement*)rootElement {
return rootElement;
}
+/*
+ Returns a pretty string representation of the document with newlines
+ and tabs.
+*/
- (NSString*)prettyXML {
if (rootElement != nil)
{
@@ -162,6 +190,10 @@ - (NSString*)prettyXML {
return nil;
}
+/*
+ Returns a compact string representation of the document without newlines
+ or tabs.
+*/
- (NSString*)xml {
if (rootElement != nil)
{
View
72 APElement.m
@@ -27,10 +27,16 @@ @implementation APElement
@synthesize name;
@synthesize parent;
+/*
+ Returns a new element with the specified tag name
+*/
+ (id)elementWithName:(NSString*)aName {
return [[[APElement alloc] initWithName:aName] autorelease];
}
+/*
+ Returns a new element with the specified tag name and attributes
+*/
+ (id)elementWithName:(NSString*)aName attributes:(NSDictionary*)someAttributes {
APElement *anElement = [[[APElement alloc] initWithName:aName] autorelease];
[anElement addAttributes:someAttributes];
@@ -38,6 +44,9 @@ + (id)elementWithName:(NSString*)aName attributes:(NSDictionary*)someAttributes
return anElement;
}
+/*
+ Initializes the element with the specified tag name
+*/
- (id)initWithName:(NSString*)aName {
if (self = [super init])
{
@@ -51,17 +60,24 @@ - (id)initWithName:(NSString*)aName {
return self;
}
+/*
+ Adds the specified attribute to the element
+*/
- (void)addAttribute:(APAttribute*)anAttribute {
[attributes setObject:anAttribute.value forKey:anAttribute.name];
}
+/*
+ Adds the specified name and value as an attribute for the element
+*/
- (void)addAttributeNamed:(NSString*)aName withValue:(NSString*)aValue {
[attributes setObject:aValue forKey:aName];
}
/*
+ Adds a dictionary of name/values to the element.
All keys and values in the supplied dictionary must be of type NSString*
- */
+*/
- (void)addAttributes:(NSDictionary*)someAttributes {
if (someAttributes != nil)
{
@@ -69,10 +85,16 @@ - (void)addAttributes:(NSDictionary*)someAttributes {
}
}
+/*
+ Adds the specified element as a child of the receiver.
+*/
- (void)addChild:(APElement*)anElement {
[childElements addObject:anElement];
}
+/*
+ Appends the specified string to the element's text value
+*/
- (void)appendValue:(NSString*)aValue {
if (value == nil)
value = [[NSMutableString alloc] init];
@@ -80,18 +102,33 @@ - (void)appendValue:(NSString*)aValue {
[value appendString:aValue];
}
+/*
+ Returns the number of attributes on this element
+*/
- (int)attributeCount {
return [attributes count];
}
+/*
+ Returns the number of child elements
+*/
- (int)childCount {
return [childElements count];
}
+/*
+ Returns an array of APElements that are direct descendants of this element.
+ Returns an empty array if the element has no children.
+*/
- (NSArray*)childElements {
return [NSArray arrayWithArray:childElements];
}
+/*
+ Returns an array of APElements that are direct descendants of this element
+ and have the specified tag name.
+ Returns an empty array if the element has no children.
+*/
- (NSMutableArray*)childElements:(NSString*)aName {
NSMutableArray *result = [[[NSMutableArray alloc] init] autorelease];
@@ -106,6 +143,10 @@ - (NSMutableArray*)childElements:(NSString*)aName {
return result;
}
+/*
+ Returns the first direct descendant of this element.
+ Returns nil if the element has no children.
+*/
- (APElement*)firstChildElement {
if ([childElements count] > 0)
return [childElements objectAtIndex:0];
@@ -113,6 +154,10 @@ - (APElement*)firstChildElement {
return nil;
}
+/*
+ Returns the first direct descendant with the specified tag name.
+ Returns nil if the element has no matching child.
+*/
- (APElement*)firstChildElementNamed:(NSString*)aName {
int numElements = [childElements count];
for (int i=0; i<numElements; i++)
@@ -125,6 +170,9 @@ - (APElement*)firstChildElementNamed:(NSString*)aName {
return nil;
}
+/*
+ Returns the text content of the element, or nil if there is none.
+*/
- (NSString*)value {
if (value == nil)
return nil;
@@ -132,14 +180,26 @@ - (NSString*)value {
return [NSString stringWithString:value];
}
+/*
+ Returns the value for the specified attribute name.
+ Returns nil if no such attribute exists
+*/
- (NSString*)valueForAttributeNamed:(NSString*)aName {
return [attributes objectForKey:aName];
}
+/*
+ Returns a human readable description of this element
+*/
- (NSString*)description {
return name;
}
+/*
+ Returns an xml string of the element, its attributes and children.
+ Useful for debugging.
+ Simply specify 0 for the tabs argument.
+*/
- (NSString*)prettyXML:(int)tabs {
NSMutableString *xmlResult = [[[NSMutableString alloc] init] autorelease];
// append open bracket and element name
@@ -177,6 +237,10 @@ - (NSString*)prettyXML:(int)tabs {
}
}
+/*
+ Returns an xml string containing a compact representation of this element, its attributes
+ and children.
+*/
- (NSString*)xml {
NSMutableString *xmlResult = [[[NSMutableString alloc] init] autorelease];
// append open bracket and element name
@@ -211,6 +275,10 @@ - (NSString*)xml {
}
}
+/*
+ Encodes the predeclared entities in the specified string, and returns a new encoded
+ string.
+*/
- (NSString*)encodeEntities:(NSMutableString*)aString {
if (aString == nil || [aString length] == 0)
return nil;
@@ -238,7 +306,7 @@ - (NSString*)encodeEntities:(NSMutableString*)aString {
options:0
range:NSMakeRange(0, [result length])];
- return result;
+ return [result autorelease];
}
- (void)dealloc {
Please sign in to comment.
Something went wrong with that request. Please try again.