#FreeKDL - KDL parsing library for C

FreeKDL is an ANSI C compliant library for reading and writing KDL files. It has minimal dependencies, and configurable memory allocation.

Features:

• Portable, ANSI C compliant
• No dependencies other than stddef.h and stdint.h
• Full UTF-8 support
• No recursion while parsing
• All memory allocation user controllable
• All malloc and realloc failures handled gracefully
• Permissive MIT licensing

#Documentation

The freekdl.h header is thoroughly commented and is intended as the primary source of documentation.

const char *kdlStr = "..."; // UTF-8 string containing the KDL document. May contain NULL bytes.
size_t kdlStrLen = 1234; // Length of kdlStr in bytes, if 0 FreeKDL will strlen() the input
struct fkdl_document doc = {0}; // In memory representation of a KDL document
struct fkdl_allocator allocator = {
  // specify malloc, realloc, free here
  // Or pass NULL into readDocument to default to the libc implementations
};
struct fkdl_error error; // Receives information about errors encountered
if (!fkdl_readDocument(kdlStr, kdlStrLen, &doc, &allocator, &error)) {
  // Handle error
}
printf("first node's identifier: %s\n", doc.nodes[0].identifier.data);

#Portability

FreeKDL consists of a single C source file, and header file which are trivial to add to your project. It also only depends on stddef.h and stdint.h, meaning that it'll compile and run almost anywhere.

#No recursion while parsing

Recursion is not used while parsing. This prevents a malicious KDL file with 1,000,000 levels of nesting from overflowing the stack. Instead memory is allocated as needed through the fkdl_allocator passed in.

#Memory allocation

FreeKDL allows users to pass in a fkdl_allocator struct that defines malloc, realloc, and free operations, as well as a custom void *context, that will be passed to the aforementioned functions. This allows users of this library to use any custom allocator desired, or to set hard memory limits on FreeKDL.

In addition, FreeKDL checks the result of all malloc and realloc calls, and will fail gracefully if either fails.

#Null byte tolerant

FreeKDL handles null bytes in strings gracefully. All internal string logic uses an explicit len variable in fkdl_string. However, for user convenience a NULL-terminator is appended to all fkdl_strings (not counted in len).

#License

Copyright 2021 Harry Jeffery

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.