diff --git a/docs/commit_messages.txt b/docs/commit_messages.txt index 8b137891791fe96927ad78e64b0aad7bded08bdc..bfe5375aa668245990dee4da6f3cef9c5467d411 100644 --- a/docs/commit_messages.txt +++ b/docs/commit_messages.txt @@ -1 +1,155 @@ +Toplevel files: + +sefht.geany: + For developing I use the IDE Geany. This file contains the + project description as well as all open files. It is included + in the VCS, because it is practical to have the position where + it was last worked on when switching branches. However this + file also often creates merge conflicts, which could be avoided, + if this file was not tracked by the VCS. + +configure.ac: + This package uses the GNU Autotools. + +main.c: + As this project is about a library, a main.c would not be + expected. It contains a small demo program using the library. + +todo.txt: + Contains features, that are discovered to be needed, + but aren't yet implemented. + + +General: +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. + 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. + 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. + There might be some cases, where it does not make sense or + it isn't possible to provide the user with some opportunity to + e.g. save a file. But it is not decidable in a library, + whether there is an option to inform the user, something must + be cleaned up or even that recovering is possible at all. + A lot of these recognized errors are a failing malloc or an + over-/underflow. + + Error handling can be ignored by the caller by passing NULL to + the Error parameter. Whether an error had occurred, is also + always possible to be determined, by examining the return + value. [citation needed] + If the error occurs in a function returning a pointer, NULL will + be returned. If it returns a value, a special error value of + that type is returned, i.e. PAGE_ERR in SH_Data_register_page. + If the return type would be void otherwise, a boolean is + returned, which tells, whether the method has succeeded. + (FALSE means, that an error has occurred.) + + The error may have occurred in an internal method and is passed + upwards (the stack). + Internally, errors are handled by an enum, but this must be + considered an implementation detail and can be changed in later + versions. + It is in the responsibility of the caller to recover gracefully. + It has to be assumed that the requested operation have neither + worked, nor actually took place. [citation needed] + Those the operation can be retried (hopefully). + +Classes: +CMS: + This class bundles some features and might be the entry point + of the library in the future. At the moment it doesn't do much. + - Pages are hold by Data, CMS passes trough the call(s). + +Data: + This class will handle Data needed by the CMS, provides storage + for modules, manages the database connection and maybe also + contains some caches. At the moment it only provides access to + the Validator. + +Fragment: + Fragment is the core of SeFHT. (As the name suggests) + It represents a Node inside the DOM and all subsequent + Nodes (a Tree). + A Fragment can contain childs. When building the html, the + childs html is generated where appropiate. + The methods + - SH_Fragment_get_child (by index) + - SH_Fragment_is_child (non recursive) and + - SH_Fragment_is_descendant (recursive) + were added. + Fragment can be copied, either recursive (copying also all + childs) or nonrecursive (ignoring the childs, thus the copy + has always no childs). + Adding the same element twice in the tree (graph) isn't + possible, as this would lead to problems e.g. double free or + similar quirks. + A Fragment can output it's html. If there is an error the method + aborts and returns NULL. + When the wrap mode is used, after each tag a newline is started. + Also the html is indented, which can be configured by the + parameters indent_base, indent_step and indent_char. The + parameter indent_base specifies the width the first tag should + be indented with, while indent_step specifies the increment of + the indent when switching to a child tag. The character, that is + used for indenting is taken from indent_char. (It could also be + a string longer than a single character). + This arguments can't be set by the user, but are hardcoded + (by now). + +Validator: + Validator serves as an syntax checker, i.e. it can be requested + whether a tag is allowed. + On initialization (of data), the Validator's knowledge is filled + with some common tags. This is of course to be replaced later, + by some dynamic handling. + When a tag is made known to the Validator, which it already + knows, the old id is returned and nothing is added. + +Text: + This is a data type to deal with frequently appending to a string. + The space a Text has for saving the string is allocated in chunks. + To request additional space SH_Text_enlarge is called. If the + requested size fits inside the already allocated space or is even + smaller than the current size, nothing is done. Otherwise a + multiple of chunk size is allocated beeing equal or greater than + the requested size. The chunk size can be changed by changing + the macro CHUNK_SIZE in src/text.h. The default is 64. + The adjustment is done automatically when a string is added. + SH_Text_append_string can be used to append a string to the text, + SH_Text_append_text can be used to append another text to the text. + SH_Text_join is a wrapper for SH_Text_append_text, but also frees + the second text, thus joining the texts to a single one. + + +Tests: + Tests are done using check, allowing to integrate the tests + into the GNU Autotools. + Methods that are part of another unit, but are called in a unit + aren't tested as this would interfere with the idea of unittests. + This applies for purely wrapper functions, where a call is just + passed to another unit. + Because sometimes an overflow condition is checked, it is + necessary to include the sourcefile into the test, instead of + linking against the objectfile. This also allows for the + separate testing of static functions, as the static keyword + can be overridden with an empty macro. + Sometimes it isn't possible to check for correct overflow + detection by setting some number to ..._MAX, because this + number is used, thus a SIGSEGV would be raised. This is solved + by filling garbage until ..._MAX is really reached. Because + there is a timeout for the tests and it would fill RAM with + gigabytes of garbage, ..._MAX is overridden prior to inclusion + of the sourcefile. + +TODO: +Log: + It is useful for debugging to actually see the error messages. diff --git a/sefht.geany b/sefht.geany index 3ae8bdbad4873b0baa9ba2f4deea01129d64a860..270c62b3a37e86c3948aba2cd61badfcd0558719 100644 --- a/sefht.geany +++ b/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=0;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fdocs%2Fcommit_messages.txt;0;8 +FILE_NAME_5=4740;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