C ORM 0.1
This is an experimental and incomplete C library, exploring a variety of ideas:
You could call this an "opinionated" library, because it tries to follow various ideas to their logical conclusion. But I'm not so keen on that term, because I'm not so certain that the ideas are good. So this library is partly an experiment in seeing how useful certain ideas can be.
Because of this "opinionated" nature, it may take some time to understand what the code is doing. The rest of this document is intended as a very rapid introduction to the various ideas.
The minimum that the external user needs to know is that non-zero (true) return values indicate an error. These codes are defined in isti_flow.h.
But if you read any of the implementation code then you will benefit from understanding that:
statusand is defined via the STATUS macro;
exit:and defined via the EXIT macro;
None of these macros are complex. They are used simply to encourage uniform, consistent handling of status values.
Most header files define a library, implemented in the similarly named source file. Libraries are defined as structs, named via macros. This gives a form of namespacing. For example:
(The error handling in this code is described above.)
It's standard practice for "good quality" C libraries to "hide" implementation details, exposing only
void* pointers as Abstract Data Types (see, for example, Hanson's C Interfaces and Implementations). However, many other languages (particularly Python) take a different approach, exposing the information while trusting the user to use it carefully.
This latter approach is sometimes called "lightweight" because, with less information hidden, less functionality needs to be provided by the library - you can use existing tools to manipulate exposed data.
In this library, data structures are generally visible. So, for example, you can access the
char* contents of a string directly (isti_str). And you are expected to do so. But (obviously?) you should not change the value unless you are very sure that you know what you are doing.