Merge pull request #4 from hrszpuk/dev

v0.2.0

README.md

@@ -1,9 +1,26 @@
-# odin-ini
-An Odin package for parsing and serializing INI config files!
-
-### Features
-- Fastest INI parser and serializer written in Odin.
-- Supports comments, sections, nested sections, and key-value pairs.
-- Highly customizable `Options` struct for parsing and serializing.
-- Supports custom memory allocation.
-- Full UTF-8 support.
+<p align="center">
+    <img width=500 src="./.github/ini-logo.png" alt="Odin-ini">
+</p>
+
+<p align="center">
+    An Odin package for parsing and serializing INI config files!
+</p>
+
+<p align="center">
+<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+<img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/hrszpuk/odin-ini">
+<a href="https://github.com/hrszpuk/odin-ini/issues"><img src="https://img.shields.io/github/issues/hrszpuk/odin-ini"></a>
+</p>
+
+<h3 align="center">
+    Features
+</h3>
+
+<ul>
+    <li>Blazingly fast INI parsing and serializing written in 100% pure Odin.</li>
+    <li>Supports comments, sections, nested sections, and key-value pairs.</li>
+    <li>Highly customizable <code>Options</code> struct for parsing and serializing.</li>
+    <li>Easy error handling with custom error modes and messages.</li>
+    <li>Custom conversion API along with built-in support for JSON conversion.</li>
+    <li>Full UTF-8 support.</li>
+</ul>

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/src/SUMMARY.md

@@ -3,14 +3,20 @@
 [Introduction](introduction.md)
 - [Installation](installation.md)
 - [Getting Started](getting_started/index.md)
-  - [Parsing INI Files](getting_started/parsing_ini_files.md)
-  - [Creating INI Files](getting_started/creating_ini_files.md)
-  - [Serializing INI Files](getting_started/serializing_ini_files.md)
+  - [Parsing INI files](getting_started/parsing_ini_files.md)
+  - [Creating INI files](getting_started/creating_ini_files.md)
+  - [Modifying INI files](getting_started/modifying_ini_files.md)
+  - [Extracting data](getting_started/getting_data_from_a_config.md)
+  - [Serializing INI files](getting_started/serializing_ini_files.md)
 - [Advanced Usage](advanced_usage/index.md)
   - [Configuration Options](advanced_usage/configuration_options.md)
   - [Error Handling](advanced_usage/error_handling.md)
   - [Conversion to/from JSON](advanced_usage/conversion_to_json.md)
   - [Custom Conversions](advanced_usage/custom_conversions.md)
 - [API Reference](api_reference/index.md)
+  - [Config](api_reference/config.md)
+  - [Options](api_reference/options.md)
+  - [Error](api_reference/error.md)
+  - [Conversion](api_reference/conversion.md)
 - [Examples](examples/index.md)
 [Contributing](contributing.md)

docs/src/api_reference/config.md

@@ -0,0 +1,176 @@
+# Config
+The `Config` struct is the main data structure used to store the configuration data. 
+I
+
+The `Config` struct is defined as follows:
+
+```odin
+Config :: struct {
+    name: string,
+    keys: map[string]^Config,
+}
+```
+
+## new_config(name: string = "config.ini") -> ^Config
+Creates a new pointer to a `Config` struct.
+
+```odin
+config := ini.new_config()
+```
+
+## destroy_config(config: ^Config)
+Deletes the `Config` struct and frees the memory.
+
+```odin
+ini.destroy_config(config)
+```
+
+## read_from_string(s: string) -> ^Config
+Reads content from a string and parses it into the `Config` struct.
+
+```odin
+config := ini.read_from_string("[section]\nkey=value")
+ini.destroy_config(config) // free config memory
+```
+
+## read_from_file(filename: string) -> ^Config
+Reads content from a file and parses it into the `Config` struct.
+
+```odin
+config := ini.read_from_file("config.ini")
+ini.destroy_config(config) // free config memory
+```
+
+## read_from_handle(h: os.Handle) -> ^Config
+Reads data from a file handle and parses it into the `Config` struct.
+
+```odin
+file := os.open("config.ini", os.ModeRead)
+config := ini.read_from_handle(file)
+ini.destroy_config(config) // free config memory
+```
+
+## write_to_string(c: ^Config) -> string
+Writes the `Config` struct to a string.
+
+```odin
+config := ini.read_from_string("[section]\nkey=value")
+s := ini.write_to_string(config)
+
+delete(s) // free memory
+ini.destroy_config(config) // free config memory
+```
+
+## write_to_file(c: ^Config) -> bool
+Writes the `Config` struct to a file. Filename is stored in the `name` field of the `Config` struct.
+
+```odin
+config := ini.read_from_string("[section]\nkey=value")
+config.name = "my_config.ini"
+ini.write_to_file(config)
+ini.destroy_config(config) // free config memory
+```
+
+## write_to_handle(c: ^Config, h: os.Handle) 
+Writes the `Config` struct to a file handle.
+
+```odin
+config := ini.read_from_string("[section]\nkey=value")
+file := os.open("my_config.ini", os.ModeWrite)
+ini.write_to_handle(config, file)
+ini.destroy_config(config) // free config memory
+```
+
+## write_to_json(c: ^Config) -> string
+Writes the `Config` struct to a JSON string.
+
+```odin
+config := ini.read_from_string("[section]\nkey=value")
+s := ini.write_to_json(config)
+
+delete(s) // free memory
+ini.destroy_config(config) // free config memory
+```
+
+
+## get(c: ^Config, key: string) -> string
+Gets the value of a key from the `Config` struct.
+This can also be used to get the key of a section because internally they are `^Config`.
+
+```odin
+config := ini.read_from_string("n=10\n[section]\nkey=value")
+value := ini.get(config, "n")
+
+ini.destroy_config(config) // free config memory
+```
+
+## get_key
+
+
+## get_section
+
+
+## add_section
+
+
+## set
+
+
+## set_key
+
+
+## set_section
+
+
+## remove
+
+
+## remove_key
+
+
+## remove_section
+
+
+## has_key
+
+
+## has_section
+
+
+## is_empty
+
+
+## clear
+
+
+## remove_all
+
+
+## size
+
+
+## depth
+
+
+## keys
+
+
+## values
+
+
+## sections
+
+
+## all_keys
+
+
+## all_values
+
+
+## all_sections
+
+
+## flatten
+
+
+## merge

docs/src/api_reference/conversion.md

@@ -0,0 +1 @@
+# Conversion

docs/src/api_reference/error.md

@@ -0,0 +1 @@
+# Error

docs/src/api_reference/index.md

@@ -1 +1,8 @@
 # API Reference
+API reference for the `odin-ini` package:
+- [Config](./config.md)
+- [Options](./options.md)
+- [Error](./error.md)
+- [Conversion](./conversion.md)
+
+For examples on how to use the library, check out the [Examples](../examples/index.md) section.

docs/src/api_reference/options.md

@@ -0,0 +1 @@
+# Options

docs/src/getting_started/creating_ini_files.md

@@ -1 +1,20 @@
-# Creating INI Files
+# Creating INI files
+Reading a pre-existing ini config is not the only way to use the library. You can also create a new config from scratch using the `new_config` function.
+
+`new_config` will accept a string argument which will be the name of the config file.
+This name can be overridden when we write the config to a file.
+It defaults to `"config.ini"`.
+```odin
+package main
+
+import "core:fmt"
+import "path/to/odin-ini/"
+
+main :: proc() {
+    config := new_config("config.ini")
+    defer ini.destroy_config(config)
+    
+    ini.set(config, "count", "42")
+}
+
+```

docs/src/getting_started/getting_data_from_a_config.md

@@ -0,0 +1,47 @@
+# Extracting data
+You can read data from a config using the `get` procedures:
+- `get`: alias for `get_key`
+- `get_key`: get a key-value pair in the config (or section)
+- `get_section`: get a section in the config
+- `exists`: alias for `exists_key`
+- `exists_key`: check if a key exists in the config
+- `exists_section`: check if a section exists in the config
+
+All of these procedures use the `optional-ok` semantics provided by Odin.
+
+```odin
+package main
+
+import "core:fmt"
+import "path/to/odin-ini/"
+
+main :: proc() {
+    config := ini.read_from_file("config.ini")
+    defer ini.destroy_config(config)
+    
+    // Get a key-value pair
+    count := ini.get(config, "count") or_else "0"
+    
+    // Get a key-value pair from a section
+    section, ok := ini.get_section(config, "section")
+    if ok {
+        key, ok := ini.get(section, "key")
+    }
+    
+    // Check if a key exists
+    if ini.exists(config, "count") {
+        fmt.println("Count exists")
+    }
+    
+    // Check if a section exists
+    if ini.exists_section(config, "section") {
+        fmt.println("Section exists")
+
+        // Check if a key exists in a section
+        if ini.exists(section, "key") {
+            fmt.println("Key exists in section")
+        }
+    }
+}
+
+```

docs/src/getting_started/index.md

@@ -1 +1,6 @@
 # Getting Started
+To get started using `odin-ini` you need to import the package into your Odin project:
+```odin
+import "path/to/odin-ini/"
+```
+Then you can start using the library to parse, create, and serialize INI files.

docs/src/getting_started/modifying_ini_files.md

@@ -0,0 +1,40 @@
+# Modifying INI files
+You've already seen some of the modification procedures in the previous examples. Here are some more examples of how you can modify an INI file:
+```odin
+package main
+
+import "core:fmt"
+import "path/to/odin-ini/"
+
+main :: proc() {
+    config := ini.read_from_file("config.ini")
+    defer ini.destroy_config(config)
+    
+    // Set a key-value pair
+    ini.set(config, "count", "42")  // Internally this is handled by `set_key`
+    
+    // Set a key-value pair in a section
+    // If a section doesn't exist it will be created
+    ini.set(config, "section", "key", "value") // Internally this is handled by `set_section_key`
+    
+    // Add a new section
+    // If a section already exists it will be overwritte
+    // Returns a pointer to the new section that can be used in `set` directly
+    section := ini.add_section(config, "new_section")
+    
+    // Set a key-value pair in the new section
+    ini.set(section, "key", "value")
+    
+    // Remove a key-value pair
+    ini.remove(config, "count") // Internally this is handled by `remove_key`
+    
+    // Remove a key-value pair from a section
+    ini.remove(config, "section", "key") // Internally this is handled by `remove_section_key`
+    
+    // Remove a section and all its key-value pairs
+    ini.remove_section(config, "new_section")
+    
+    // Write the config to a file
+    ini.write_to_file(config)
+}
+```