docs: collect commit messages #3

Up to (and including) commit e572e78b
'renamed macros'

docs/commit_messages.txt

@@ -45,14 +45,53 @@ Compilation:
 	is to test for the internal state.
 
 Error handling:
-	Error handling is done by passing an Error structure as an
-	inout parameter to functions that can fail on runtime
-	predictably. This parameter is always the last one. Methods,
-	where there is no error, that can be detected on runtime,
-	don't have an error parameter.
+	Error handling is done by the status structure. The name was
+	chosen in favour of error, because status is also set
+	independently whether an error has occurred.
+	The structure must be allocated by the caller,
+	because allocation errors may need to be handled, and in such a
+	case, it is unlikely, that it is possible to allocate memory.
+	Every function, that can fail predictably on runtime, supports
+	passing a pointer to a status structure as the last parameter.
+	Functions that can't fail detectably, doesn't have the parameter.
+
+	The structure contains an error type, the errno, the filename,
+	the function name, the line number and a message.
+	There are the following error types:
+	undefined: only needed to test, whether a function properly sets
+		the status parameter, might be removed in the future.
+	SUCCESS: no error has occurred.
+	E_ALLOC: allocation failure: malloc/realloc/calloc or strdup etc.
+	E_DOMAIN: Something is not representable due to a chosen type.
+		For example, there are more elements in an array, then
+		the index type supports.
+	E_VALUE: Some parameter had an erroneous value. For example,
+		an index out of bounds or a non existing reference.
+	E_STATE: Something is unfulfillable, due to some constraint.
+	E_BUG: Some unconsistent state was encountered. This always
+		indicates some bug in the library, not in the user
+		program, for this E_VALUE or E_STATE are used. However,
+		it might be caused by the user program manipulating
+		internals.
+	The filename, function name and line number point to the file,
+	where the error has occurred in the first place. This might not
+	be the function, that is called from the outside; filename and
+	function name are null-terminated strings allocated on compiletime.
+	The message, might be allocated on compiletime or during runtime.
+
+	The proper way of accessing the status structure is yet to be
+	defined. Currently the structure is accessed directly, but it
+	has to be considered an implementation detail. There are also
+	macros to check for a set status.
+
 	When an Error is detected, also an ERROR is passed to the log.
 	Because this isn't implemented yet, it is replaced by a call
 	to printf.
+
+	Unfortunately the compiler reports, that inside the macro
+	set_status, printf may be called with NULL [printf (NULL)],
+	although, this is explicitly debarred.
+
 	Some may argue, that in case of a fatal error, like if no memory
 	can be allocated, a program should just give up and crash.
 	However this behaviour is not very user-friendly.
@@ -168,6 +207,36 @@ Validator:
 	When a tag is made known to the Validator, which it already
 	knows, the old id is returned and nothing is added.
 
+	The Validator saves the tags as an array. Now also another information
+	is added, which slots aren't used currently to spare expensive calls to
+	realloc. This led to a mere reimplementation of the functions. Tags
+	can't be deleted by now, but the adding function supports reusing empty
+	slots. Also the reading functions have to determine, whether a slot can
+	be read or is empty.
+	The tests were adjusted, but are buggy, so they should be rewritten in
+	the future.
+
+	A registered tag can be deregistered by calling SH_Validator_deregister.
+	The data is removed, but the space is not deallocated, if it is not at
+	the end. This prevents copying data on removal and saves expensive calls
+	to realloc. Instead the empty space is added to the list of free blocks,
+	which allows to refill these spaces, if a new tag is being registered.
+	The space is finally deallocated, if the validator is being deallocated
+	or the tag written in the last block is removed. In this case, heavy
+	iteration is performed, as the list of free blocks is not ordered. The
+	next last tag at that time is determined by iterating over the list of
+	free blocks until some it is not found.
+	Note that even if there can be a lot of gaps in between, the Validator
+	will not allocate more space until all these gaps are refilled when a
+	new tag is registered, thus new space is only being allocated, if there
+	is really not enough space left.
+	Due to the 4 nested loops, there was an issue related to the
+	72(80)-column rule. It can't be abided without severely impacting the
+	readability of the code.
+
+	Copying a Validator could be useful if multiple html versions are to be
+	supported. Another use case is a blacklist XSS-Scanner.
+
 Text:
 	This is a data type to deal with frequently appending to a string.
 

sefht.geany

@@ -34,7 +34,7 @@ FILE_NAME_1=134;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2F
 FILE_NAME_2=1737;Sh;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fconfigure.ac;0;8
 FILE_NAME_3=73;Make;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2FMakefile.am;0;8
 FILE_NAME_4=19;C;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Fmain.c;0;8
-FILE_NAME_5=1831;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fdocs%2Fcommit_messages.txt;0;8
+FILE_NAME_5=10380;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fdocs%2Fcommit_messages.txt;0;8
 FILE_NAME_6=1867;Make;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Flib%2FMakefile.am;0;8
 FILE_NAME_7=18;C;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Flib%2Fsefht%2Fcms.c;0;8
 FILE_NAME_8=18;C;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Flib%2Fsefht%2Fcms.h;0;8