From e3be05fe045b7484acbf27a5b9e2fe35659a853b Mon Sep 17 00:00:00 2001 From: Richard Frith-Macdonald Date: Mon, 11 Nov 2002 10:18:49 +0000 Subject: [PATCH] Documentation added git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@14974 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 5 ++ Source/NSString.m | 183 ++++++++++++++++++++++++++++++++++++++++ Source/NSUserDefaults.m | 22 ++--- Tools/AGSHtml.m | 10 +-- 4 files changed, 205 insertions(+), 15 deletions(-) diff --git a/ChangeLog b/ChangeLog index c93f74cb5..0e9d519d3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2002-11-11 Richard Frith-Macdonald + + * Source/NSString.m: adocument property list stuff. + * Source/NSUserDefaults.m: set integers, floats and bools as NSNumber + 2002-11-10 Richard Frith-Macdonald * Headers/gnustep/base/NSObject.h: Removed GNUstep plist extensions. diff --git a/Source/NSString.m b/Source/NSString.m index 9b497af77..7efe2e752 100644 --- a/Source/NSString.m +++ b/Source/NSString.m @@ -3870,11 +3870,194 @@ handle_printf_atsign (FILE *stream, return [super replacementObjectForPortCoder: aCoder]; } +/** + *

Attempts to interpret the receiver as a property list + * and returns the result. If the receiver does not contain a + * string representation of a property list then the method + * returns nil. + *

+ *

There are three readable property list storage formats - + * The binary format used by [NSSerializer] does not concern us here, + * but there are two 'human readable' formats, the traditional + * OpenStep format (which is extended in GNUstep) and the XML format. + *

+ *

The [NSArray-descriptionWithLocale:indent:] and + * [NSDictionary-descriptionWithLocale:indent:] methods + * both generate strings containing traditional style property lists, + * but [NSArray-writeToFile:atomically:] and + * [NSDictionary-writeToFile:atomically:] generate either traditional or + * XML style property lists depending on the value of the + * GSMacOSXCompatible and NSWriteOldStylePropertyLists user defaults.
+ * If GSMacOSXCompatible is YES then XML property lists are + * written unless NSWriteOldStylePropertyLists is also YES.
+ * By default GNUstep writes old style data and always supports reading of + * either style. + *

+ *

The traditional format is more compact and more easily readable by + * people, but (without the GNUstep extensions) cannot represent date and + * number objects (except as strings). The XML format is more verbose and + * less readable, but can be fed into modern XML tools and thus used to + * pass data to non-OpenStep applications more readily. + *

+ *

The traditional format is strictly ascii encoded, with any unicode + * characters represented by escape sequences. The XML format is encoded + * as UTF8 data. + *

+ *

Both the traditional format and the XML format permit comments to be + * placed in property list documents. In traditional format the + * comment notations used in ObjectiveC programming are supported, while + * in XML format, the standard SGML comment sequences are used. + *

+ * A property list may only be one of the following classes - + * + * [NSArray] + * + * An array which is either empty or contains only property list + * objects.
+ * An array is delimited by round brackets and its contents are comma + * separated (there is no comma after the last array element). + * + * ( "one", "two", "three" ) + * + * In XML format, an array is an element whose name is array + * and whose content is the array content. + * + * <array><string>one</string><string>two</string><string>three</string></array> + * + * + * [NSData] + * + * An array is represented as a series of pairs of hexadecimal characters + * (each pair representing a byte of data) enclosed in angle brackets. + * Spaces are ignored). + * + * < 54637374 696D67 > + * + * In XML format, a data object is an element whose name is + * data and whose content is a stream of base64 encoded bytes. + * + * [NSDate] + * + * Date objects were not traditionally allowed in property lists + * but were added when the XML format was intoroduced. GNUstep provides + * an extension to the traditional property list format to + * support date objects, but older code will not read + * property lists containing this extension.
+ * This format consists of an asterisk follwed by the letter 'D' then a + * date/time in YYYY-MM-DD HH:MM:SS +/-ZZZZ format, all enclosed within + * angle brackets. + * + * <*D2002-03-22 11:30:00 +0100> + * + * In XML format, a date object is an element whose name is + * date and whose content is a date in the above format. + * + * <date>2002-03-22 11:30:00 +0100</date> + * + * + * [NSDictionary] + * + * A dictionary which is either empty or contains only string + * keys and property list objects.
+ * A dictionary is delimited by curly brackets and its contents are + * semicolon terminated (there is a semicolon after each value). + * Each item in the dictionary is a key/value pair with an equals sign + * after the key and before the value. + * + * { + * "key1" = "value1"; + * } + * + * In XML format, a dictionary is an element whose name is + * dictionary and whose content consists of pairs of + * strings and other property list objects. + * + * <dictionary> + * <string>key1</string> + * <string>value1</string> + * </dictionary> + * + * + * [NSNumber] + * + * Number objects were not traditionally allowed in property lists + * but were added when the XML format was intoroduced. GNUstep provides + * an extension to the traditional property list format to + * support number objects, but older code will not read + * property lists containing this extension.
+ * Numbers are stored in a variety of formats depending on their values. + * + * boolean ... either <*BY> for YES or + * <*BN> for NO.
+ * In XML format this is either <true /> or + * <false /> + * + * integer ... <*INNN> where NNN is an + * integer.
+ * In XML format this is <integer>NNN<integer> + * + * real ... <*RNNN> where NNN is a real + * number.
+ * In XML format this is <real>NNN<real> + * + * + * + * [NSString] + * + * A string is either stored literally (if it contains no spaces or special + * characters), or is stored as a quoted string with special characters + * escaped where necessary.
+ * Escape conventions are similar to those normally used in ObjectiveC + * programming, using a backslash followed by - + * + * \ a backslash character + * " a quote character + * b a backspace character + * n a newline character + * r a carriage return character + * t a tab character + * OOO (three octal digits) + * an arbitrary ascii character + * UXXXX (where X is a hexadecimal digit) + * a an arbitrary unicode character + * + * + * "hello world & others" + * + * In XML format, the string is simply stored in UTF8 format as the + * content of a string element, and the only character + * escapes required are those used by XML such as the + * '&lt;' markup representing a '<' character. + * + * <string>hello world &amp; others</string>" + * + * + * + */ - (id) propertyList { return GSPropertyList(self); } +/** + *

Reads a property list (see -propertyList) from a simplified + * file format. This format is a traditional style property list file + * containing a single dictionary, but with the leading '{' and trailing + * '}' characters omitted. + *

+ *

That is to say, the file contains only semicolon separated key/value + * pairs (and optionally comments). As a convenience, it is possible to + * omit the equals sign and the value, so an entry consists of a key string + * followed by a semicolon. In this case, the value for that key is + * assumed to be an empty string. + *

+ * + * // Strings file entries follow - + * key1 = " a string value"; + * key2; // This key has an empty string as a value. + * "Another key" = "a longer string value for th third key"; + * + */ - (NSDictionary*) propertyListFromStringsFileFormat { return GSPropertyListFromStringsFormat(self); diff --git a/Source/NSUserDefaults.m b/Source/NSUserDefaults.m index a145c7e2d..55f7e57f1 100644 --- a/Source/NSUserDefaults.m +++ b/Source/NSUserDefaults.m @@ -998,9 +998,9 @@ static NSString *pathForUser(NSString *user) */ - (void) setBool: (BOOL)value forKey: (NSString*)defaultName { - id obj = (value)?@"YES": @"NO"; + NSNumber *n = [NSNumber numberWithBool: value]; - [self setObject: obj forKey: defaultName]; + [self setObject: n forKey: defaultName]; return; } @@ -1010,10 +1010,9 @@ static NSString *pathForUser(NSString *user) */ - (void) setFloat: (float)value forKey: (NSString*)defaultName { - char buf[32]; + NSNumber *n = [NSNumber numberWithFloat: value]; - sprintf(buf,"%g",value); - [self setObject: [NSStringClass stringWithCString: buf] forKey: defaultName]; + [self setObject: n forKey: defaultName]; return; } @@ -1023,10 +1022,9 @@ static NSString *pathForUser(NSString *user) */ - (void) setInteger: (int)value forKey: (NSString*)defaultName { - char buf[32]; + NSNumber *n = [NSNumber numberWithInt: value]; - sprintf(buf,"%d",value); - [self setObject: [NSStringClass stringWithCString: buf] forKey: defaultName]; + [self setObject: n forKey: defaultName]; return; } @@ -1085,10 +1083,14 @@ static BOOL isPlistObject(id o) } /** - * Sets an object value for defaultName in the application domain. - *
Causes a NSUserDefaultsDidChangeNotification to be posted + * Sets an object value for defaultName in the application domain.
+ * The defaultName must be a non-empty string.
+ * The value must be an instance of one of the [NSString-propertyList] + * classes.
+ *

Causes a NSUserDefaultsDidChangeNotification to be posted * if this is the first change to a persistent-domain since the * last -synchronize. + *

*/ - (void) setObject: (id)value forKey: (NSString*)defaultName { diff --git a/Tools/AGSHtml.m b/Tools/AGSHtml.m index bd75e4e66..991afe3d5 100644 --- a/Tools/AGSHtml.m +++ b/Tools/AGSHtml.m @@ -1801,24 +1801,24 @@ NSLog(@"Element '%@' not implemented", name); // FIXME [buf appendString: @"

\n"]; [self incIndent]; } - return [node nextElement]; + return [node next]; } else if ([n isEqual: @"example"] == YES) { [buf appendString: @"

\n"];
 	  [self outputText: [node firstChild] to: buf];
 	  [buf appendString: @"\n
\n"]; - return [node nextElement]; + return [node next]; } else if ([n isEqual: @"embed"] == YES) { NSLog(@"Element 'embed' not supported"); - return [node nextElement]; + return [node next]; } else if ([n isEqual: @"index"] == YES) { [self outputNode: node to: buf]; - return [node nextElement]; + return [node next]; } else if ([textNodes member: n] != nil) { @@ -1969,7 +1969,7 @@ NSLog(@"Element '%@' not implemented", name); // FIXME { return node; // Not a list } - node = [node nextElement]; + node = [node next]; return node; }