Differences From
Artifact [58fe849cf0]:
188 188
189 189 1. it should be easy to write code that uses it.
190 190 2. it should be easy to read code that uses it.
191 191 3. the simple, obvious way of using libk should produce the most optimal code.
192 192 4. code that uses libk should be idiomatic C.
193 193
194 194 for these reasons, the codebase follows a number of strict rules.
195 -
196 -### booleans are banned
195 +
196 +## booleans are banned
197 197 there are a number of reasons for this.
198 198
199 199 the first is simply that the boolean type in C is a bit messy and libk headers are intended to import as few extra files as possible.
200 200
201 201 the second is that boolean-using code can be hard to read. consider a struct declaration of the form `rule r = { 10, buf, true, false, true }`: the meaning of this declaration is opaque unless you've memorized the structure's definition.
202 202
203 203 instead, libk uses enums liberally. so the above might be rewritten as e.g.:
................................................................................
205 205 rule r = { 10, buf,
206 206 rule_kind_undialectical,
207 207 rule_action_expropriate,
208 208 rule_target_bourgeoisie
209 209 };
210 210
211 211 this makes code much more legible and has the added benefit of making the definitions easier to expand at a later date if new functionality is needed without breaking the API or ABI.
212 +
213 +## error handling
214 +every module has a `cond` type (e.g. `kscond` for `kstr` or `kconf_cond` for `kconf`). this is an enumeration type that represents every possible error a module can return, and every `cond` type obeys a number of invariants (in addition to the usual namespacing rules:
215 +
216 +1. every member of a cond type has a globally unique integer value. this means that `kscond_ok` has an integer value is not equal to `kmcond_ok`.
217 +2. every member of a cond type has a member `kmcond_ok` which represents success. this member's integer value is always an exact multiple of the "module offset", the number of condition values allocated to each module (currently `0x7F`).
218 +3. the `kokay()` function, defined in `kcore`, when called on a member of a `cond` type will return true if that member represents total success and false otherwise.
219 +4. every cond type has a value `*cond_fail`, for instance `kconf_cond_fail`. if a condition is greater than or equal to its module's `fail` value, it represents a total failure. if it is lesser than the fail value, it represents either success, partial success, or some other condition that does not equate to total failure.
220 +
221 +the reason each error value is unique is that this allows us to map every single condition code unambiguously to an error message. a forthcoming `kcore` function will do exactly that and produce an error string that can be displayed to a user or for debugging purposes. another useful property is that each integer value has at most only one possible meaning in the context of error codes, allowing for centralized error handling - a `kscond` and a `kmcond` can both be turned into an `int` without loss of information; and e.g. `kscond_fail` != `kmcond_fail` != `kconf_cond_fail`.
222 +
223 +this is particularly useful as C does not have exceptions, and thus the only viable error-handling mechanisms are early-exit and early-return; any `cond` value can be propagated up the function stack without losing its unique meaning.
224 +
225 +the value of each condition code is determined at compile time.
212 226
213 227 # authors
214 228
215 229 * lexi `velartrill` hale <lexi@hale.su>
216 230 * lachs0r
217 231 * glowpelt
218 232