Reformats Readme to provide better instructions
This makes the Readme much cleaner so new users have an easier time starting out with this library.
This commit is contained in:
dcresswell
parent
a1d23056ac
commit
e1e7369907
156
README.md
156
README.md
|
|
@ -1,95 +1,125 @@
|
|||
# tomlc99
|
||||
|
||||
TOML in c99; v0.5.0 compliant.
|
||||
|
||||
|
||||
# Usage
|
||||
## Usage
|
||||
|
||||
Please see the `toml.h` file for details. What follows is a simple example that
|
||||
parses this config file:
|
||||
|
||||
```
|
||||
```toml
|
||||
[server]
|
||||
host = "www.example.com"
|
||||
port = 80
|
||||
host = "www.example.com"
|
||||
port = 80
|
||||
```
|
||||
|
||||
For each config param, the code first extracts a raw value and then
|
||||
convert it to a string or integer depending on context.
|
||||
The steps for getting values from our file is usually :
|
||||
|
||||
1. Parse the whole TOML file.
|
||||
2. Get a single table from the file.
|
||||
3. Find a value from the table.
|
||||
4. Convert that value to the appropriate type (I.E. string, int).
|
||||
5. Then, free up that memory if needed.
|
||||
|
||||
Below is an example of parsing the values from the example table.
|
||||
|
||||
1. Parse the whole TOML file.
|
||||
|
||||
```c
|
||||
FILE* fp;
|
||||
toml_table_t* conf;
|
||||
char errbuf[200];
|
||||
|
||||
/* Open the file. */
|
||||
if (0 == (fp = fopen("path/to/file.toml", "r"))) {
|
||||
return handle_error();
|
||||
}
|
||||
|
||||
/* Run the file through the parser. */
|
||||
conf = toml_parse_file(fp, errbuf, sizeof(errbuf));
|
||||
if (0 == conf) {
|
||||
return handle_error();
|
||||
}
|
||||
|
||||
fclose(fp);
|
||||
|
||||
/* Alternatively, use `toml_parse` which takes a string rather than a file. */
|
||||
conf = toml_parse("A null terminated string that is TOML\0", errbuf, sizeof(errbuf);
|
||||
```
|
||||
|
||||
FILE* fp;
|
||||
toml_table_t* conf;
|
||||
toml_table_t* server;
|
||||
const char* raw;
|
||||
char* host;
|
||||
int64_t port;
|
||||
char errbuf[200];
|
||||
2. Get a single table from the file.
|
||||
|
||||
/* open file and parse */
|
||||
if (0 == (fp = fopen(FNAME, "r"))) {
|
||||
return handle_error();
|
||||
}
|
||||
conf = toml_parse_file(fp, errbuf, sizeof(errbuf));
|
||||
fclose(fp);
|
||||
if (0 == conf) {
|
||||
return handle_error();
|
||||
}
|
||||
```c
|
||||
toml_table_t* server;
|
||||
|
||||
/* locate the [server] table */
|
||||
if (0 == (server = toml_table_in(conf, "server"))) {
|
||||
/* Locate the [server] table. */
|
||||
if (0 == (server = toml_table_in(conf, "server"))) {
|
||||
return handle_error();
|
||||
}
|
||||
|
||||
/* extract host config value */
|
||||
if (0 == (raw = toml_raw_in(server, "host"))) {
|
||||
return handle_error();
|
||||
}
|
||||
if (toml_rtos(raw, &host)) {
|
||||
return handle_error();
|
||||
}
|
||||
|
||||
/* extract port config value */
|
||||
if (0 == (raw = toml_raw_in(server, "port"))) {
|
||||
return handle_error();
|
||||
}
|
||||
if (toml_rtoi(raw, &port)) {
|
||||
return handle_error();
|
||||
}
|
||||
|
||||
/* done with conf */
|
||||
toml_free(conf);
|
||||
|
||||
/* use host and port */
|
||||
do_work(host, port);
|
||||
|
||||
/* clean up */
|
||||
free(host);
|
||||
}
|
||||
```
|
||||
|
||||
3. Find a value from the table.
|
||||
4. Convert that value to the appropriate type (I.E. string, int).
|
||||
|
||||
# Building
|
||||
```c
|
||||
const char* raw;
|
||||
char* host;
|
||||
int64_t port;
|
||||
|
||||
/* Extract 'host' config value. */
|
||||
if (0 == (raw = toml_raw_in(server, "host"))) {
|
||||
return handle_error();
|
||||
}
|
||||
|
||||
/* Convert the raw value into a string. */
|
||||
if (toml_rtos(raw, &host)) {
|
||||
return handle_error();
|
||||
}
|
||||
|
||||
/* Extract 'port' config value. */
|
||||
if (0 == (raw = toml_raw_in(server, "port"))) {
|
||||
return handle_error();
|
||||
}
|
||||
|
||||
/* Convert the raw value into an int. */
|
||||
if (toml_rtoi(raw, &port)) {
|
||||
return handle_error();
|
||||
}
|
||||
```
|
||||
|
||||
5. Then, free up that memory if needed.
|
||||
|
||||
```c
|
||||
/* Use `toml_free` on the table returned from `toml_parse[_file]`. */
|
||||
toml_free(conf);
|
||||
|
||||
/* Free any values returned from `toml_rto*`. */
|
||||
free(host);
|
||||
free(port);
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
A normal *make* suffices. Alternately, you can also simply include the
|
||||
`toml.c` and `toml.h` files in your project.
|
||||
|
||||
# Testing
|
||||
## Testing
|
||||
|
||||
To test against the standard test set provided by BurntSushi/toml-test:
|
||||
|
||||
```
|
||||
% make
|
||||
% cd test1
|
||||
% bash build.sh # do this once
|
||||
% bash run.sh # this will run the test suite
|
||||
```sh
|
||||
% make
|
||||
% cd test1
|
||||
% bash build.sh # do this once
|
||||
% bash run.sh # this will run the test suite
|
||||
```
|
||||
|
||||
|
||||
To test against the standard test set provided by iarna/toml:
|
||||
|
||||
```
|
||||
% make
|
||||
% cd test2
|
||||
% bash build.sh # do this once
|
||||
% bash run.sh # this will run the test suite
|
||||
```sh
|
||||
% make
|
||||
% cd test2
|
||||
% bash build.sh # do this once
|
||||
% bash run.sh # this will run the test suite
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue