ObjFW  Check-in [494dca4ae4]

1.) Basic Concept

This document describes the serialization used by ObjFW. It is designed to be
easy parsable and usable in other programming languages while still supporting
ObjFW-specific features, which are all optional.

Every object can have a set of parameters which are optional and can be ignored
if they don't exist in the language for which parsing is done. These parameters
are written in the form (parameter1,parameter2) and precede the object.
Parameters not known by the implementation should be ignored - they are
completely optional except for the extension type.

All spaces (except those in strings, of course) are optional and only to improve
readability - they are by no means required, but they are still recommended.

ObjFW serialization supports 4 basic types: Strings, arrays and dictionaries.
It is limited to those 4 types because those are available in all languages.
Lists are a special case of arrays in ObjFW serialization. For all objects
that can not be serialized with those 4 basic types, there is the extension
type [], which can be used for any object but is not portable between languages.
This type is described in 6.).


2.) Strings

Strings are very similar to how strings are done in C. They start with a " and
end with a ". The escape sequences \", \\, \n, \r and \t exist, like in C
strings. It is required to use \", \\, \n and \r. The reason for this is that
using an actual newline would modify the string when indention is done. However,
using \t is recommended.
Strings can be split just like in C. For example "Hello " "World" is equivalent
to "Hello World". Because this is possible, it is recommended to end the string
after \n and continue it in a new line to increase readability.

Strings are required to be UTF-8 encoded.

The only accepted parameter for strings is mutable. If the language for which
parsing is done does not know the concept of mutable and immutable objects, this
parameter should be ignored.

Examples for strings:

	"This is a \"string!\""

	"This is a string containing a\n"
	    "new line!"

	"This is\ta string\tcontaining tabs!"

	(mutable)"This string is mutable!"


3.) Arrays

Arrays start with a [ and end with an ]. The elements are separated by a comma.
Whitespaces are allowed between objects and after the inital [ and before the
final ].

It allows the mutable parameter, which should be handled the same way like it
should be for strings.

It also has the list parameter. Specifying this parameter creates a
double-linked list instead of an array.

It also allows specifying a number as a parameter. This number is considered
the expected size of the array. It is by no means required and it should by no
means be assumed to be reliable. If the number is not equal to the actual size,
the parser should error out. The parser should also make sure to ignore the
number if it is too big to prevent a possible DoS.

Examples for arrays:

	["This", "is", "an", "array", "with", "7", "strings"]

	(mutable)["This array", "is mutable"]

	(3)["This array specifies", "the number of elements", "for performance"]

	(mutable,2)["Parameters can be", "combined"]


4.) Dictionaries

Dictionary start with a { and end with a }. The elements are written in the form
key = value and each entry ends with an ;.

It allows the mutable parameter, which should be handled the same way like it
should be for strings.

It also allows specifying a number as a parameter, which should be handled
exactly like for arrays.

Examples for dictionaries:

	{"This is a key" = "This is a value"}

	(mutable){"mutable" = (BOOL)1}

	(2){
		"key1" = "value1",
		"key2" = "value2"
	}

	{
		["Mapping", "an", "array"] = "To a string";
		{ "mapping" = "a dictionary" } = ["To", "an", "array"];
	}


5.) Numbers

Numbers are written by just writing a number. The type of a number may be
specified by a parameter. If it is not specified, the implementation should
choose are type which fits the number. If the specified type is not big enough
for the number, the implementation should use another type that fits.

Known parameters are:
	BOOL
	char		(signed!)
	short		(signed!)
	int		(signed!)
	long		(signed!)
	int8_t
	int16_t
	int32_t
	int64_t
	unsigned char,
	unsigned short,
	unsigned int,
	unsigned long
	uint8_t
	uint16_t
	uint32_t
	uint64_t
	size_t
	ssize_t
	intmax_t
	uintmax_t
	intptr_t
	uintptr_t
	float
	double

Examples for numbers:

	1
	2.6
	(BOOL)0
	(intmax_t)1234567
	(double)2.5


6.) Extension Type

The extension type allows adding new objects to ObjFW serialization. The
extension type has a parameter class= which specifies the class which should
handle deserialization and a version= parameter which specifies the version of
the class serialization as a single integer. The extension type starts with a [
and ends with a ]. Inside those brackets can be arbitray basic types, which
should be passed unmodified to the class for deserialization.
If an implementation can't deserialize an extension type, it is required to
error out. Other languages are allowed to parse extension types of classes which
are in ObjFW, like OFXMLElement, but are by no means required to do so. Other
languages may also add their own extension types, but are required to add the
foreign= parameter and set it to their name, so other implementations don't try
to deserialize it, but error out instead. Other implementations are allowed to
serialize to ObjFW objects if they know them. For example, it might be desirable
to also create OFXMLElements from other languages.

Examples for using the extension type:

	(class=OFXMLElement)<"<some-xml/>">

 	(class=OFURL)<
		"https://webkeks.org/objfw/"
	>

 	(class=Foo,foreign=Foolang)<
		{
			"property1" = "value1"
		}
	>

#include "config.h"

#include <stdarg.h>

#import "OFArray.h"
#import "OFDataArray.h"
#import "OFString.h"

#import "OFAutoreleasePool.h"

#import "OFEnumerationMutationException.h"
#import "OFOutOfRangeException.h"

#import "macros.h"

	 * to be OFString*, so it can't be modified anyway. But not swizzling it
	 * would create a real copy each time -[copy] is called.
	 */
	ret->isa = [OFString class];
	return ret;
}

- (OFString*)stringBySerializing
{
	OFAutoreleasePool *pool;
	OFMutableString *ret;
	OFObject <OFSerialization> **cArray;
	size_t i, count;

	if ([array count] == 0) {
		if ([self isKindOfClass: [OFMutableArray class]])
			return @"(mutable,0)[]";
		else
			return @"(0)[]";
	}

	cArray = [array cArray];
	count = [array count];
	if ([self isKindOfClass: [OFMutableArray class]])
		ret = [OFMutableString stringWithFormat: @"(mutable,%zd)[\n",
							 count];
	else
		ret = [OFMutableString stringWithFormat: @"(%zd)[\n", count];
	pool = [[OFAutoreleasePool alloc] init];



	for (i = 0; i < count - 1; i++) {
		[ret appendString: [cArray[i] stringBySerializing]];
		[ret appendString: @",\n"];

		[pool releaseObjects];
	}
	[ret appendString: [cArray[i] stringBySerializing]];
	[ret replaceOccurrencesOfString: @"\n"
			     withString: @"\n\t"];
	[ret appendString: @"\n]"];

	[pool release];

	/*
	 * Class swizzle the string to be immutable. We declared the return type
	 * to be OFString*, so it can't be modified anyway. But not swizzling it
	 * would create a real copy each time -[copy] is called.
	 */
	ret->isa = [OFString class];
	return ret;
}

- (void)makeObjectsPerformSelector: (SEL)selector
{
	id *cArray = [array cArray];
	size_t i, count = [array count];

#include <time.h>

#include <sys/time.h>

#import "OFDate.h"
#import "OFString.h"
#import "OFDictionary.h"
#import "OFNumber.h"
#import "OFAutoreleasePool.h"
#ifdef OF_THREADS
# import "OFThread.h"
#endif

#import "OFInitializationFailedException.h"
#import "OFInvalidArgumentException.h"

}

- (OFString*)description
{
	return [self dateStringWithFormat: @"%Y-%m-%dT%H:%M:%SZ"];
}

- (OFString*)stringBySerializing
{
	OFAutoreleasePool *pool = [[OFAutoreleasePool alloc] init];
	OFDictionary *dictionary = [OFDictionary dictionaryWithKeysAndObjects:
	    @"seconds", [OFNumber numberWithInt64: seconds],


	    @"microseconds", [OFNumber numberWithUInt32: microseconds], nil];
	OFString *ret = [[OFString alloc]
	    initWithFormat: @"(class=OFDate,version=0)<%@>",
			    [dictionary stringBySerializing]];

	@try {
		[pool release];

	} @finally {


		[ret autorelease];




	}


	return ret;
}

- (uint32_t)microsecond
{
	return microseconds;
}

#include <string.h>

#import "OFDictionary.h"
#import "OFEnumerator.h"
#import "OFArray.h"
#import "OFString.h"

#import "OFAutoreleasePool.h"

#import "OFEnumerationMutationException.h"
#import "OFInvalidArgumentException.h"
#import "OFOutOfRangeException.h"

#import "macros.h"

	 * to be OFString*, so it can't be modified anyway. But not swizzling it
	 * would create a real copy each time -[copy] is called.
	 */
	ret->isa = [OFString class];
	return ret;
}

- (OFString*)stringBySerializing
{
	OFMutableString *ret;
	OFAutoreleasePool *pool, *pool2;

	OFEnumerator *keyEnumerator, *objectEnumerator;
	id key, object;
	size_t i;

	if (count == 0) {
		if ([self isKindOfClass: [OFMutableDictionary class]])
			return @"(mutable,0){}";
		else
			return @"(0){}";

	}

	if ([self isKindOfClass: [OFMutableDictionary class]])
		ret = [OFMutableString stringWithFormat: @"(mutable,%zd){\n",
							 count];
	else
		ret = [OFMutableString stringWithFormat: @"(%zd){\n", count];
	pool = [[OFAutoreleasePool alloc] init];



	keyEnumerator = [self keyEnumerator];
	objectEnumerator = [self objectEnumerator];

	i = 0;
	pool2 = [[OFAutoreleasePool alloc] init];

	while ((key = [keyEnumerator nextObject]) != nil &&
	    (object = [objectEnumerator nextObject]) != nil) {

		[ret appendString: [key stringBySerializing]];


		[ret appendString: @" = "];



		[ret appendString: [object stringBySerializing]];







		if (++i < count)
			[ret appendString: @",\n"];

		[pool2 releaseObjects];
	}
	[ret replaceOccurrencesOfString: @"\n"
			     withString: @"\n\t"];
	[ret appendString: @"\n}"];

	[pool release];

	/*
	 * Class swizzle the string to be immutable. We declared the return type
	 * to be OFString*, so it can't be modified anyway. But not swizzling it
	 * would create a real copy each time -[copy] is called.
	 */
	ret->isa = [OFString class];
	return ret;
}
@end

@implementation OFDictionaryEnumerator
- initWithDictionary: (OFDictionary*)dictionary_
		data: (struct of_dictionary_bucket**)data_
		size: (uint32_t)size_

#include "config.h"

#include "assert.h"

#import "OFList.h"
#import "OFString.h"

#import "OFAutoreleasePool.h"

#import "OFEnumerationMutationException.h"

#import "macros.h"

@implementation OFList

	 * to be OFString*, so it can't be modified anyway. But not swizzling it
	 * would create a real copy each time -[copy] is called.
	 */
	ret->isa = [OFString class];
	return ret;
}

- (OFString*)stringBySerializing
{
	OFMutableString *ret;
	OFAutoreleasePool *pool;

	of_list_object_t *iter;

	if (count == 0)
		return @"(list,mutable)[]";

	ret = [OFMutableString stringWithString: @"(list,mutable)[\n"];
	pool = [[OFAutoreleasePool alloc] init];



	for (iter = firstListObject; iter != NULL; iter = iter->next) {
		[ret appendString: [iter->object stringBySerializing]];

		if (iter->next != NULL)
			[ret appendString: @",\n"];

		[pool releaseObjects];
	}
	[ret replaceOccurrencesOfString: @"\n"
			     withString: @"\n\t"];
	[ret appendString: @"\n]"];

	[pool release];

	/*
	 * Class swizzle the string to be immutable. We declared the return type
	 * to be OFString*, so it can't be modified anyway. But not swizzling it
	 * would create a real copy each time -[copy] is called.
	 */
	ret->isa = [OFString class];
	return ret;
}

- (int)countByEnumeratingWithState: (of_fast_enumeration_state_t*)state
			   objects: (id*)objects
			     count: (int)count_
{
	of_list_object_t **list_obj = (of_list_object_t**)state->extra;

	state->itemsPtr = objects;
	state->mutationsPtr = &mutations;

	if (state->state == 0) {
		*list_obj = firstListObject;
		state->state = 1;
	}

	if (*list_obj == NULL)
		return 0;

	objects[0] = (*list_obj)->object;
	*list_obj = (*list_obj)->next;
	return 1;
}

- (OFEnumerator*)objectEnumerator
{
	return [[[OFListEnumerator alloc]
	        initWithList: self

#include "config.h"

#include <math.h>

#import "OFNumber.h"
#import "OFString.h"



#import "OFInvalidFormatException.h"
#import "OFNotImplementedException.h"

#import "macros.h"

#define RETURN_AS(t)							\

	case OF_NUMBER_DOUBLE:
		return [OFString stringWithFormat: @"%lf", value.double_];
	default:
		@throw [OFInvalidFormatException newWithClass: isa];
	}
}

- (OFString*)stringBySerializing
{












	switch (type) {
	case OF_NUMBER_BOOL:

		return (value.bool_ ? @"<BOOL>1" : @"<BOOL>0");

	case OF_NUMBER_UCHAR:
		return [OFString stringWithFormat: @"<unsigned char>%hhu",
						   value.uchar];
	case OF_NUMBER_USHORT:
		return [OFString stringWithFormat: @"<unsigned short>%hu",
						   value.ushort];
	case OF_NUMBER_UINT:
		return [OFString stringWithFormat: @"<unsigned int>%u",
						   value.uint];
	case OF_NUMBER_ULONG:
		return [OFString stringWithFormat: @"<unsigned long>%lu",
						   value.ulong];
	case OF_NUMBER_UINT8:
		return [OFString stringWithFormat: @"<uint8_t>%" @PRIu8,
						   value.uint8];
	case OF_NUMBER_UINT16:
		return [OFString stringWithFormat: @"<uint16_t>%" @PRIu16,
						   value.uint16];
	case OF_NUMBER_UINT32:
		return [OFString stringWithFormat: @"<uint32_t>%" @PRIu32,
						   value.uint32];
	case OF_NUMBER_UINT64:
		return [OFString stringWithFormat: @"<uint64_t>%" @PRIu64,
						   value.uint64];
	case OF_NUMBER_SIZE:
		return [OFString stringWithFormat: @"<size_t>%ju",
						   (uintmax_t)value.size];
	case OF_NUMBER_UINTMAX:
		return [OFString stringWithFormat: @"<uintmax_t>%ju",
						   value.uintmax];
	case OF_NUMBER_UINTPTR:
		return [OFString stringWithFormat: @"<uintptr_t>%" @PRIuPTR,
						   value.uintptr];

	case OF_NUMBER_CHAR:
		return [OFString stringWithFormat: @"<char>%hhd",
						   value.char_];
	case OF_NUMBER_SHORT:
		return [OFString stringWithFormat: @"<short>%hd",
						   value.short_];
	case OF_NUMBER_INT:
		return [OFString stringWithFormat: @"<int>%d",
						   value.int_];
	case OF_NUMBER_LONG:
		return [OFString stringWithFormat: @"<long>%ld",
						   value.long_];
	case OF_NUMBER_INT8:
		return [OFString stringWithFormat: @"<int8_t>%" @PRId8,
						   value.int8];
	case OF_NUMBER_INT16:
		return [OFString stringWithFormat: @"<int16_t>%" @PRId16,
						   value.int16];
	case OF_NUMBER_INT32:
		return [OFString stringWithFormat: @"<int32_t>%" @PRId32,
						   value.int32];
	case OF_NUMBER_INT64:
		return [OFString stringWithFormat: @"<int64_t>%" @PRId64,
						   value.int64];
	case OF_NUMBER_SSIZE:
		return [OFString stringWithFormat: @"<ssize_t>%jd",
						   (intmax_t)value.ssize];
	case OF_NUMBER_INTMAX:
		return [OFString stringWithFormat: @"<intmax_t>%jd",
						   value.intmax];
	case OF_NUMBER_PTRDIFF:
		return [OFString stringWithFormat: @"<ptrdiff_t>%td" @PRIdPTR,
						   value.ptrdiff];
	case OF_NUMBER_INTPTR:

		return [OFString stringWithFormat: @"<intptr_t>%" @PRIdPTR,
						   value.intptr];
	case OF_NUMBER_FLOAT:
		return [OFString stringWithFormat: @"<float>%f",

						   value.float_];

	case OF_NUMBER_DOUBLE:
		return [OFString stringWithFormat: @"<double>%lf",

						   value.double_];

	default:
		@throw [OFInvalidFormatException newWithClass: isa];
	}
}




@end

 * Alternatively, it may be distributed under the terms of the GNU General
 * Public License, either version 2 or 3, which can be found in the file
 * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this
 * file.
 */

@class OFString;




/**
 * \brief A protocol for serializing objects.
 */
@protocol OFSerialization <OFObject>
/**
 * \brief Serializes the object into a string.


 */
- (OFString*)stringBySerializing;
@end

#import "OFString.h"
#import "OFArray.h"
#import "OFDictionary.h"
#import "OFFile.h"
#import "OFURL.h"
#import "OFHTTPRequest.h"

#import "OFAutoreleasePool.h"

#import "OFHTTPRequestFailedException.h"
#import "OFInitializationFailedException.h"
#import "OFInvalidArgumentException.h"
#import "OFInvalidEncodingException.h"
#import "OFInvalidFormatException.h"

}

- (OFString*)description
{
	return [[self copy] autorelease];
}

- (OFString*)stringBySerializing
{
	OFMutableString *serialization = [[self mutableCopy] autorelease];
	[serialization replaceOccurrencesOfString: @"\\"
				       withString: @"\\\\"];
	[serialization replaceOccurrencesOfString: @"\""
				       withString: @"\\\""];
	[serialization replaceOccurrencesOfString: @"\n"
				       withString: @"\\n\"\n    \""];
	[serialization replaceOccurrencesOfString: @"\r"
				       withString: @"\\r"];
	[serialization replaceOccurrencesOfString: @"\t"
				       withString: @"\\t"];


	if ([self isKindOfClass: [OFMutableString class]])

		[serialization prependString: @"(mutable)\""];
	else
		[serialization prependString: @"\""];
	[serialization appendString: @"\""];


	/*
	 * Class swizzle the string to be immutable. We declared the return type
	 * to be OFString*, so it can't be modified anyway. But not swizzling it
	 * would create a real copy each time -[copy] is called.
	 */
	serialization->isa = [OFString class];
	return serialization;
}

- (of_unichar_t)characterAtIndex: (size_t)index
{
	of_unichar_t c;

	if (![self isUTF8]) {

#include <stdlib.h>
#include <string.h>
#include <assert.h>

#import "OFURL.h"
#import "OFString.h"
#import "OFArray.h"

#import "OFAutoreleasePool.h"

#import "OFInvalidArgumentException.h"
#import "OFInvalidFormatException.h"
#import "OFOutOfMemoryException.h"

#import "macros.h"

}

- (OFString*)description
{
	return [self string];
}

- (OFString*)stringBySerializing
{
	OFAutoreleasePool *pool = [[OFAutoreleasePool alloc] init];
	OFString *ret = [[OFString alloc]
	    initWithFormat: @"(class=OFURL,version=0)<%@>",
			    [[self string] stringBySerializing]];


	@try {
		[pool release];
	} @finally {
		[ret autorelease];


	}


	return ret;
}
@end

 */

#include "config.h"

#import "OFXMLAttribute.h"
#import "OFString.h"
#import "OFDictionary.h"

#import "OFAutoreleasePool.h"

@implementation OFXMLAttribute
+ attributeWithName: (OFString*)name
	  namespace: (OFString*)ns
	stringValue: (OFString*)value
{

}

- (OFString*)stringValue
{
	return [[stringValue copy] autorelease];
}

- (OFString*)stringBySerializing
{
	OFAutoreleasePool *pool = [[OFAutoreleasePool alloc] init];

	OFMutableDictionary *dictionary = [OFMutableDictionary dictionary];


	OFString *ret;


	if (name != nil)

		[dictionary setObject: name

			       forKey: @"name"];


	if (ns != nil)
		[dictionary setObject: ns

			       forKey: @"namespace"];

	if (stringValue != nil)
		[dictionary setObject: stringValue

			       forKey: @"stringValue"];

	dictionary->isa = [OFDictionary class];

	ret = [[OFString alloc]
	    initWithFormat: @"(class=OFXMLElement,version=0)<%@>",
			    [dictionary stringBySerializing]];

	@try {
		[pool release];
	} @finally {
		[ret autorelease];
	}

	return ret;
}
@end

}

- (OFString*)description
{
	return [self XMLString];
}

- (OFString*)stringBySerializing
{
	OFAutoreleasePool *pool = [[OFAutoreleasePool alloc] init];

	OFMutableDictionary *dictionary = [OFMutableDictionary dictionary];


	OFString *ret;





	if (name != nil)



		[dictionary setObject: name
			       forKey: @"name"];
	if (ns != nil)



		[dictionary setObject: ns
			       forKey: @"namespace"];
	if (defaultNamespace != nil)

		[dictionary setObject: defaultNamespace

			       forKey: @"defaultNamespace"];

	if (attributes != nil)


		[dictionary setObject: attributes
			       forKey: @"attributes"];
	if (namespaces != nil)
		[dictionary setObject: namespaces
			       forKey: @"namespaces"];
	if (children != nil)
		[dictionary setObject: children
			       forKey: @"children"];
	if (characters != nil)
		[dictionary setObject: characters
			       forKey: @"characters"];
	if (CDATA != nil)
		[dictionary setObject: CDATA
			       forKey: @"CDATA"];
	if (comment != nil)
		[dictionary setObject: comment
			       forKey: @"comment"];

	dictionary->isa = [OFDictionary class];



	ret = [[OFString alloc]
	    initWithFormat: @"(class=OFXMLElement,version=0)<%@>",


			    [dictionary stringBySerializing]];


	@try {


		[pool release];






	} @finally {





		[ret autorelease];





	}








	return ret;
}

- (void)addAttribute: (OFXMLAttribute*)attribute
{
	if (name == nil)
		@throw [OFInvalidArgumentException newWithClass: isa
						       selector: _cmd];