Merge pull request #10 from choco-technologies/copilot/add-documentation-for-visibility-restrictions

docs: add section visibility restriction API documentation

Author: JohnAmadis

README.md

@@ -16,11 +16,13 @@ dmini is a lightweight INI file parser/generator module designed for embedded sy
 - **Global Section Support**: Handle keys without section headers
 - **Comment Support**: Parse comments starting with `;` or `#`
 - **Whitespace Trimming**: Automatic trimming of keys and values
+- **Section Visibility Restriction**: Limit the visible scope of a context to a single section, with optional token-based protection
 
 ## API
 
 ### Context Management
 - `dmini_create()` - Create INI context
+- `dmini_create_with_token(owner_token)` - Create INI context protected by an owner token
 - `dmini_destroy()` - Free INI context
 
 ### Parsing
@@ -41,6 +43,10 @@ dmini is a lightweight INI file parser/generator module designed for embedded sy
 - `dmini_has_section(ctx, section)` - Check if section exists
 - `dmini_has_key(ctx, section, key)` - Check if key exists
 
+### Section Visibility Restriction
+- `dmini_set_active_section(ctx, section, owner_token)` - Restrict the context to a single section
+- `dmini_clear_active_section(ctx, owner_token)` - Remove the section restriction
+
 ### Removal
 - `dmini_remove_section(ctx, section)` - Remove entire section
 - `dmini_remove_key(ctx, section, key)` - Remove single key
@@ -76,6 +82,47 @@ dmini_generate_file(ctx, "output.ini");
 dmini_destroy(ctx);
 ```
 
+## Section Visibility Restriction
+
+The section visibility restriction feature allows a context to be locked to a
+single section. While the restriction is active all API calls treat
+`section == NULL` as a reference to the active section, and any attempt to
+access a different section returns not-found / the default value.
+
+This is useful when you want to pass a context to a component that should only
+see one section of a larger configuration file.
+
+An optional **owner token** can be set at creation time so that only the
+creator can change or clear the restriction.
+
+```c
+// Create a context protected by a token
+dmini_context_t ctx = dmini_create_with_token(0xDEADBEEF);
+
+dmini_parse_file(ctx, "config.ini");
+
+// Restrict visibility to the "network" section
+dmini_set_active_section(ctx, "network", 0xDEADBEEF);
+
+// All NULL-section calls now resolve to "network"
+const char* host = dmini_get_string(ctx, NULL, "host", "localhost");
+int port         = dmini_get_int(ctx, NULL, "port", 80);
+
+// Accessing any other section returns not-found / default
+const char* val = dmini_get_string(ctx, "database", "host", "n/a");
+// val == "n/a"
+
+// Remove the restriction (requires the correct token)
+dmini_clear_active_section(ctx, 0xDEADBEEF);
+
+dmini_destroy(ctx);
+```
+
+If a wrong token is supplied to `dmini_set_active_section()` or
+`dmini_clear_active_section()` the function returns `DMINI_ERR_LOCKED (-6)`.
+A token value of `0` disables token protection (any caller may change the
+active section).
+
 ## Building
 
 ```bash
@@ -106,6 +153,7 @@ Test coverage includes:
 - Buffer generation with size queries
 - File I/O operations
 - Comments and whitespace handling
+- Section visibility restriction (active section with and without token protection)
 
 ## INI File Format
 

apps/test_dmini/README.md

@@ -49,6 +49,7 @@ The application tests the following dmini functionality:
 
 1. **Context Management**
    - `dmini_create()` - Create INI context
+   - `dmini_create_with_token()` - Create INI context with owner token
    - `dmini_destroy()` - Free INI context
 
 2. **Parsing**
@@ -81,6 +82,11 @@ The application tests the following dmini functionality:
    - Whitespace trimming
    - Empty sections
 
+8. **Section Visibility Restriction**
+   - `dmini_set_active_section()` - Restrict context to a single section
+   - `dmini_clear_active_section()` - Remove the section restriction
+   - Token-based protection (`DMINI_ERR_LOCKED` on wrong token)
+
 ## Integration with CI
 
 The test application is automatically run as part of the CI pipeline:

docs/dmini.md

@@ -10,6 +10,7 @@ dmini - DMOD INI File Parser Module
 #include "dmini.h"
 
 dmini_context_t dmini_create(void);
+dmini_context_t dmini_create_with_token(unsigned int owner_token);
 void dmini_destroy(dmini_context_t ctx);
 
 int dmini_parse_string(dmini_context_t ctx, const char* data);
@@ -33,6 +34,10 @@ int dmini_has_key(dmini_context_t ctx, const char* section, const char* key);
 
 int dmini_remove_section(dmini_context_t ctx, const char* section);
 int dmini_remove_key(dmini_context_t ctx, const char* section, const char* key);
+
+int dmini_set_active_section(dmini_context_t ctx, const char* section,
+                              unsigned int owner_token);
+int dmini_clear_active_section(dmini_context_t ctx, unsigned int owner_token);
 ```
 
 ## DESCRIPTION
@@ -57,6 +62,11 @@ INI files consist of sections, key-value pairs, and comments:
 **dmini_create()** creates a new INI context for storing sections and 
 key-value pairs. Returns a context pointer or NULL on error.
 
+**dmini_create_with_token()** creates a new INI context protected by a magic 
+number token. The token must be supplied to **dmini_set_active_section()** and 
+**dmini_clear_active_section()** when a non-zero token is used. Passing token 
+value 0 is equivalent to calling **dmini_create()**.
+
 **dmini_destroy()** frees all memory associated with an INI context.
 
 ### Parsing
@@ -115,6 +125,20 @@ context. Returns DMINI_OK on success or an error code on failure.
 NULL for section to remove from the global section. Returns DMINI_OK on 
 success or an error code on failure.
 
+### Section Visibility Restriction
+
+**dmini_set_active_section()** restricts the context so that only the named 
+section is visible to consumers of this context. While the restriction is 
+active, all API calls treat `section == NULL` as a reference to the active 
+section, and any attempt to access a different section returns not-found / the 
+default value. Pass NULL as section to restrict to the global (unnamed) 
+section. If the context was created with a non-zero token, the matching token 
+must be supplied; otherwise DMINI_ERR_LOCKED is returned.
+
+**dmini_clear_active_section()** removes the active-section restriction so 
+that the full content of the context becomes visible again. Requires the 
+correct token when the context was created with a non-zero token.
+
 ## RETURN VALUES
 
 Functions return the following error codes:
@@ -125,6 +149,7 @@ Functions return the following error codes:
 * **DMINI_ERR_INVALID** (-3) - Invalid parameter
 * **DMINI_ERR_NOT_FOUND** (-4) - Section or key not found
 * **DMINI_ERR_FILE** (-5) - File I/O error
+* **DMINI_ERR_LOCKED** (-6) - Wrong owner token supplied to set/clear active section
 
 ## EXAMPLES
 
@@ -182,6 +207,35 @@ dmini_set_string(ctx, NULL, "global_key", "global_value");
 const char* val = dmini_get_string(ctx, NULL, "global_key", "default");
 ```
 
+### Section Visibility Restriction
+
+```c
+// Create a context protected by a token
+dmini_context_t ctx = dmini_create_with_token(0xDEADBEEF);
+
+dmini_parse_file(ctx, "config.ini");
+
+// Restrict visibility to the "network" section
+dmini_set_active_section(ctx, "network", 0xDEADBEEF);
+
+// All NULL-section calls now resolve to "network"
+const char* host = dmini_get_string(ctx, NULL, "host", "localhost");
+int port         = dmini_get_int(ctx, NULL, "port", 80);
+
+// Accessing any other section returns not-found / default
+const char* db = dmini_get_string(ctx, "database", "host", "n/a");
+// db == "n/a"
+
+// Wrong token returns DMINI_ERR_LOCKED
+int rc = dmini_clear_active_section(ctx, 0x12345678);
+// rc == DMINI_ERR_LOCKED
+
+// Correct token clears the restriction
+dmini_clear_active_section(ctx, 0xDEADBEEF);
+
+dmini_destroy(ctx);
+```
+
 ## MEMORY FOOTPRINT
 
 * **dmini library**: 536B RAM, 5KB ROM