---
title: conf.h
related:
  - "[conf.h-paper](conf.h-paper.md)"
  - "[flag.h](flag.h.md)"
  - "[vicel](vicel.md)"
  - "[tffpr](tffpr.md)"
categories:
  - C libraries
---

**conf.h** is a single-file, public domain (or MIT licensed) library that
abstracts the use of Lua config files from C and C++.

## Example

A config file for a GUI program:

```
Config = {
    font = {
        size = 26,
    }
}
```

Reading the font size:

```
Conf conf;
Conf_open(&conf, "config.lua");

double val;
Conf_get_num(conf, &val, "Config.font.size");

Conf_close(conf);
```

## Installation

conf.h needs Lua 5.1 or LuaJIT (both implement the Lua 5.1 API). Copy
`conf.h` into your project and, in exactly one C/C++ file:

```
#define INCLUDE_CONF_IMPLEMENTATION
#include "conf.h"
```

Every other file just does `#include "conf.h"`. The repository's `make`
builds against PUC-Rio Lua 5.1; `make LUA=luajit` uses LuaJIT.

## Config styles

Both global-table and return-table files work:

```
-- Global style
Config = { font = { size = 26 } }
```

```
-- Return style
return { font = { size = 26 } }
```

## Error handling

Every `Conf_*` function returns an `int` status: `CONF_OK` (0) on success,
non-zero on error. Handle it however fits your style:

```
assert(Conf_get_num(conf, &val, "Config.font.size") == CONF_OK);

if (Conf_get_num(conf, &val, "Config.font.size") != CONF_OK) {
    // error handling
}

switch (Conf_get_num(conf, &val, "Config.font.size")) {
    case CONF_OK:
    case CONF_INVALID:
    ...
}
```

Read `conf.h` for every status code.

## Used by

- [vicel](vicel.md), [tffpr](tffpr.md) and [pm](pm.md) read their
  configuration with it.

## See also

- [Source code](https://github.com/hugoocoto/conf.h)
- [conf.h-paper](conf.h-paper.md): alternatives, performance and design
  details.