tomlc17 TOML Parser

A toml_datum_t represents a node in the parsed document tree. To access the actual value, check the type field (of type toml_type_t) and then access the corresponding field in the u union.

To extract data from a parsed TOML file, use toml::Result in combination with get() or seek() methods on the retrieved Datum objects.

get() method

Use result.get({"key1", "key2"}) to retrieve a value using a list of keys representing the path to the nested element. This returns a pointer to a Datum.

seek() method

Use result.seek("key1.key2") to retrieve a value using a dot-separated string path. This also returns a pointer to a Datum.

Error Handling

Both methods return std::optional wrappers (via methods like .as_str() or .as_intvec()). If the key does not exist or the type is incorrect, calling .value() on the optional will throw std::bad_optional_access. It is recommended to wrap these calls in try-catch blocks.

Example

// Parse the file
toml::Result result = toml::parse_file_ex("simple.toml");

if (!result.ok()) {
  // Handle parse error using result.errmsg()
}

try {
  // Accessing nested string via get()
  std::string host = result.get({"server", "host"})->as_str().value();

  // Accessing nested array via seek()
  std::vector<int64_t> ports = result.seek("server.port")->as_intvec().value();
} catch (const std::bad_optional_access &ex) {
  // Handle missing or invalid properties
}

/*
 * Parse the config file simple.toml:
 *
 * [server]
 * host = "www.example.com"
 * port = [8080, 8181, 8282]
 *
 */
#include "../src/tomlcpp.hpp"
#include <iostream>
#include <vector>

using std::cout;

static void error(const char *msg) {
  fprintf(stderr, "ERROR: %s\n", msg);
  exit(1);
}

int main() {
  // Parse the toml file
  toml::Result result = toml::parse_file_ex("simple.toml");

  // Check for parse error
  if (!result.ok()) {
    error(result.errmsg());
  }

  // Extract values
  std::string host;
  std::vector<int64_t> port;

  try {
    // use the Datum::get() method
    host = result.get({"server", "host"})->as_str().value();
  } catch (const std::bad_optional_access &ex) {
    error("missing or invalid 'server.host' property in config");
  }

  try {
    // use the Datum::seek() method
    port = result.seek("server.port")->as_intvec().value();
  } catch (const std::bad_optional_access &ex) {
    error("missing or invalid 'server.port' property in config");
  }

  // Print values
  cout << "server.host = " << host << "\n";
  cout << "server.port = [";
  for (size_t i = 0; i < port.size(); i++) {
    cout << (i ? ", " : "") << port[i];
  }
  cout << "]\n";

  // Done! No need to call toml_free(). Result::~Result() will handle destruction.
  return 0;
}

To use tomlc17, follow these steps:

1. Parse: Call toml_parse(), toml_parse_file(), or toml_parse_file_ex() to parse a document.
2. Validate: Check result.ok. If false, use result.errmsg to inspect the error.
3. Navigate: Use toml_get() or toml_seek() to traverse the parsed document tree.
4. Cleanup: Call toml_free() on the result when finished.

Memory Management Rule: You must call toml_free() on every toml_result_t returned by a parse or merge function, even if result.ok is false. All strings and data returned by the API are owned by the toml_result_t and remain valid only until toml_free() is called.

#include "tomlc17.h"

// 1. Parse
toml_result_t result = toml_parse_file_ex("config.toml");

// 2. Check result
if (result.ok) {
    // 3. Navigate
    toml_datum_t val = toml_get(result.toptab, "key");
    // ... use val ...
} else {
    printf("Error: %s\n", result.errmsg);
}

// 4. Free
toml_free(result);

To use tomlc17, parse a TOML file into a tree structure using toml_parse_file_ex. You can then navigate this tree using toml_seek with dot-notation paths (e.g., "server.host") to retrieve toml_datum_t objects. Always check the ok field of the toml_result_t to ensure parsing succeeded, and verify the type of the returned datum before accessing its union members (like u.s for strings or u.int64 for integers). Finally, call toml_free to release the memory associated with the result.

/*
 * Parse the config file simple.toml:
 *
 * [server]
 * host = "www.example.com"
 * port = [8080, 8181, 8282]
 *
 */
#include "tomlc17.h"
#include <errno.h>
#include <inttypes.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>

static void error(const char *msg, const char *msg1) {
  fprintf(stderr, "ERROR: %s%s\n", msg, msg1 ? msg1 : "");
  exit(1);
}

int main() {
  // Parse the toml file
  toml_result_t result = toml_parse_file_ex("simple.toml");

  // Check for parse error
  if (!result.ok) {
    error(result.errmsg, 0);
  }

  // Extract values
  toml_datum_t host = toml_seek(result.toptab, "server.host");
  toml_datum_t port = toml_seek(result.toptab, "server.port");

  // Print server.host
  if (host.type != TOML_STRING) {
    error("missing or invalid 'server.host' property in config", 0);
  }
  printf("server.host = %s\n", host.u.s);

  // Print server.port
  if (port.type != TOML_ARRAY) {
    error("missing or invalid 'server.port' property in config", 0);
  }
  printf("server.port = [");
  for (int i = 0; i < port.u.arr.size; i++) {
    toml_datum_t elem = port.u.arr.elem[i];
    if (elem.type != TOML_INT64) {
      error("server.port element not an integer", 0);
    }
    printf("%s%" PRId64, i ? ", " : "", elem.u.int64);
  }
  printf("]\n");

  // Done!
  toml_free(result);
  return 0;
}

By default, tomlc17 uses standard C library realloc() and free() for memory management. You can override this behavior using toml_set_option() to integrate with custom memory pools, arena allocators, or to track allocations for debugging and resource constraints.

Implementation Requirements

• mem_realloc: Must behave like standard realloc():
  • If size > 0: Allocate or resize memory; return the pointer or NULL on failure.
  • If size == 0: Free the memory and return NULL.
• mem_free: Must handle NULL pointers gracefully.

Usage Constraints

• Initialization: Call toml_set_option() exactly once during program startup, before any parsing operations occur.
• Thread Safety: toml_set_option() is not thread-safe. Ensure options are set during initialization in a single-threaded context.

#include "tomlc17.h"
#include <stdlib.h>

// Custom realloc function
void* my_realloc(void *ptr, size_t size) {
  if (size == 0) {
    free(ptr);
    return NULL;
  }
  return realloc(ptr, size);
}

// Custom free function
void my_free(void *ptr) {
  free(ptr);
}

int main() {
  // Set custom allocators
  toml_option_t opt = toml_default_option();
  opt.mem_realloc = my_realloc;
  opt.mem_free = my_free;
  toml_set_option(opt);

  // Now all subsequent parse calls will use your custom allocators
  toml_result_t result = toml_parse_file_ex("config.toml");
  
  if (result.ok) {
    toml_free(result);
  }

  return 0;
}