https://github.com/ysdragon/toml
A comprehensive TOML parser for the Ring programming language
https://github.com/ysdragon/toml
ring-programming-language toml tomlc17
Last synced: 1 day ago
JSON representation
A comprehensive TOML parser for the Ring programming language
- Host: GitHub
- URL: https://github.com/ysdragon/toml
- Owner: ysdragon
- License: other
- Created: 2025-07-04T15:19:37.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-08-12T14:52:50.000Z (6 months ago)
- Last Synced: 2025-08-12T15:15:53.514Z (6 months ago)
- Topics: ring-programming-language, toml, tomlc17
- Language: Ring
- Homepage:
- Size: 396 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ring TOML
A comprehensive TOML parser extension for the Ring programming language, built as a wrapper around the [`tomlc17`](https://github.com/cktan/tomlc17) C library.
## Features
* Cross-platform (Linux, macOS, FreeBSD, and Windows).
* Parse TOML files and strings into Ring Lists.
* Supports all TOML data types, including strings, numbers, booleans, dates, times, arrays, and tables.
## Getting Started
### Installation
#### Using RingPM
```shell
ringpm install toml from ysdragon
```
#### Manual Build
##### Prerequisites
* [Ring](http://ring-lang.net) programming language (1.22 or later)
* CMake (3.5 or later)
* C compiler (GCC, Clang, or MSVC)
##### Manual Build Steps
1. **Clone the repository:**
```bash
git clone --recursive https://github.com/ysdragon/toml.git
cd toml
```
2. **Set RING environment variable to your Ring installation directory:**
On Windows (cmd):
```cmd
set RING=X:\path\to\ring
```
On Windows (PowerShell):
```powershell
$env:RING = "X:\path\to\ring"
```
On Unix-like systems:
```bash
export RING=/path/to/ring
```
3. **Build the extension:**
```bash
cmake -Bbuild -DCMAKE_BUILD_TYPE=Release
cmake --build build
```
This will compile the extension and place the resulting shared library (`libring_toml.so` on Linux or FreeBSD, `ring_toml.dll` on Windows) into the `lib//` directory.
## Usage
```ring
// Load the TOML extension
load "toml.ring"
// Parse a TOML file
pToml = toml_parse_file("examples/example.toml")
// Access data using the toml_get() function
title = toml_get(pToml, "title")
db_ip = toml_get(pToml, "database.ip_address")
first_product_name = toml_get(pToml, "products[1].name")
? "Title: " + title
? "Database IP: " + db_ip
? "First Product: " + first_product_name
// You can also convert the entire TOML structure to a Ring list
aTomlList = toml2list(pToml)
see aTomlList
```
## API Reference
### High-Level Functions
* `toml_get(pTomlResult, cPath)`: Retrieves a value from the parsed TOML data using a dot-separated path.
* `pTomlResult`: The pointer returned by `toml_parse()` or `toml_parse_file()`.
* `cPath`: A string representing the path to the desired value (e.g., `"database.user.name"`, `"products[2].sku"`).
* Returns `NULL` for invalid paths (empty, consecutive dots, leading/trailing dots).
* `toml_exists(pTomlResult, cPath)`: Checks if a key exists at the given path.
* Returns `true` if the path exists, `false` otherwise.
* `toml_keys(pTomlResult, cPath)`: Returns a list of keys at the given path.
* If `cPath` is empty or `NULL`, returns top-level keys.
* Returns `NULL` if the path doesn't exist or doesn't point to a table.
### Core Extension Functions
* `toml_parse(cTomlString)`: Parses a TOML-formatted string. Returns a pointer to the parsed result.
* `toml_parse_file(cFilePath)`: Parses a TOML file. Returns a pointer to the parsed result.
* `toml2list(pTomlResult)`: Converts the entire parsed TOML result into a Ring list.
* `toml_get_ex(pTomlResult, cKey)`: Retrieves a specific value, table, or array by its key from the top level.
* `toml_type(pTomlResult, cKey)`: Returns the TOML type of a value by its key as an integer (see Type Constants below).
* `toml_lasterror()`: Returns a string containing the last error message if a parsing operation fails.
### Type Constants
These constants are defined in `toml.rh` and can be used with `toml_type()` for type checking:
| Constant | Description |
|----------|-------------|
| `TOML_UNKNOWN` | Unknown or invalid type |
| `TOML_STRING` | String value |
| `TOML_INT64` | Integer value |
| `TOML_FP64` | Floating-point value |
| `TOML_BOOLEAN` | Boolean value |
| `TOML_DATE` | Date (YYYY-MM-DD) |
| `TOML_TIME` | Time (HH:MM:SS) |
| `TOML_DATETIME` | Date and time without timezone |
| `TOML_DATETIMETZ` | Date and time with timezone |
| `TOML_ARRAY` | Array |
| `TOML_TABLE` | Table (inline or standard) |
## Examples
The [**`examples`**](examples) directory contains several files demonstrating how to use the Ring TOML extension.
* [**`example1.ring`**](examples/example1.ring): Demonstrates basic TOML file parsing and how to access various data types using the `toml_get()` helper function.
* [**`example2.ring`**](examples/example2.ring): Shows how to parse an inline TOML string and convert the entire structure into a Ring list for easier manipulation.
* [**`example3.ring`**](examples/example3.ring): Illustrates an alternative way to access TOML data by using the `toml_get_ex()` function to directly extract arrays and tables without first converting to a list.
* [**`example4.ring`**](examples/example4.ring): Shows how to perform type checking on TOML data using the `toml_type()` function and the predefined type constants.
## Running Tests
The project includes a test suite to verify the functionality of the extension. To run the tests:
```bash
ring tests/TOML_test.ring
```
The test script will parse `tests/test.toml` and run a series of assertions against the parsed data, covering all major features of the library.
## Limitations
* **Read-only**: This library currently only supports parsing TOML. Writing/serializing Ring data structures back to TOML format is not yet supported (the underlying `tomlc17` library is parser-only).
## License
This project is licensed under the [MIT](LICENSE) License.