From 4ab0460eb4c5dd672690d9a43c9dc17a8fcb65f6 Mon Sep 17 00:00:00 2001
From: Jakob Olsson <jakob.olsson@iopsys.eu>
Date: Fri, 4 Oct 2019 09:39:48 +0200
Subject: [PATCH] README: add deleter function to docs
---
README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 53 insertions(+), 12 deletions(-)
diff --git a/README.md b/README.md
index d395884..24231e2 100644
--- a/README.md
+++ b/README.md
@@ -16,21 +16,24 @@ sudo make install
## API
-The library currently offers three features, a getter and setter accepting a javascript format string representing the syntax, and two functions reading/writing JSON to a file.
+The library currently offers four features, a getter, a setter and a deleter function, accepting a javascript format string representing the syntax, and two functions for reading/writing JSON to a file.
### Setter
-The setter function, ```json_object_set_by_string_delimiter(5)```, takes five arguments, albeit with recommended to be used through a wrapper function ```json_object_set_by_string(4)```, defaulting the delimiter to a dot,```.```.
+The setter function, ```json_object_set_by_string_delimiter(5)```, will set a value based on provided format, taking five arguments, albeit recommended to be used through a wrapper function ```json_object_set_by_string(4)```, defaulting the delimiter to a dot,```.```.
```
-int json_object_set_by_string_delimiter(struct json_object **src, char *fmt, char *val, enum json_type type, const char *delimiter)
+int json_object_set_by_string( struct json_object **src, char *fmt, char *val, enum json_type type);
+int json_object_set_by_string_delimiter( struct json_object **src, char *fmt, char *val, enum json_type type, const char *delimiter);
```
-```src``` is a pointer to the address of a ```struct json_object```, if it is a null pointer an object will be created.
-```fmt``` is a string representing the syntax pointing to the object to be set, i.e. ```device.macaddr```, note that this syntax may contain nested objects or arrays without restrictions, i.e. ```a.b[1][0].c```. Additionally, if a key, array or index is missing it will be created and added to the ```src``` pointer. *NULL represents root key.*
-```val``` represents the value to be set. This should always be presented in a string format, albeit can be used to represent integers, strings, arrays of object depending on syntax, i.e. ```{\"macaddr\":\"11:22:33:44:55:66\"}```.
-```type``` expects an enum of ```json_type```, to declare as what object type the input should be added.
-```delimiter``` is syntactical delimiter in the format string.
+#### Arguments
+
+1. ```src``` is a pointer to the address of a ```struct json_object```, if it is a null pointer an object will be created.
+2. ```fmt``` is a string representing the syntax pointing to the object to be set, i.e. ```device.macaddr```, note that this syntax may contain nested objects or arrays, i.e. ```a.b[1][0].c```. Additionally, if a key, array or index is missing it will be created and added to the ```src``` pointer. *NULL represents root key.*
+3. ```val``` represents the value to be set. This should always be presented in a string format, albeit can be used to represent integers, strings, arrays of object depending on syntax, i.e. ```{\"macaddr\":\"11:22:33:44:55:66\"}```.
+4. ```type``` expects an enum of ```json_type```, to declare as what object type the input should be added.
+5. ```delimiter``` is syntactical delimiter in the format string.
#### Example usage
@@ -52,15 +55,18 @@ For more example usage see ```test/api_test.c```.
### Getter
-The getter function, ```json_object_get_by_string_delimiter(3)```, similarily to the setter, takes five arguments, recommended to be used through a wrapper function ```json_object_get_by_string(2)```, defaulting the delimiter to a dot,```.```. If the specified format is not present in the object NULL is returned.
+The getter function, ```json_object_get_by_string_delimiter(3)```, gets a key or value based on provided format. Like the setter, recommended to be used through a wrapper function ```json_object_get_by_string(2)```, defaulting the delimiter to a dot,```.```. If the specified format is not present in the object NULL is returned.
```
+struct json_object *json_object_get_by_string(struct json_object *src, char *fmt);
struct json_object *json_object_get_by_string_delimiter(struct json_object *src, char *fmt, const char *delimiter);
```
-```src``` is a pointer to the ```struct json_object``` to traverse.
-```fmt``` is a string representing the syntax pointing to the object to be set, i.e. ```device.macaddr```, note that this syntax may contain nested objects or arrays without restrictions, i.e. ```a.b[1][0].c```.
-```delimiter``` is syntactical delimiter in the format string.
+#### Arguments
+
+1. ```src``` is a pointer to the ```struct json_object``` to traverse.
+2. ```fmt``` is a string representing the syntax pointing to the object to be set, i.e. ```device.macaddr```, note that this syntax may contain nested objects or arrays, i.e. ```a.b[1][0].c```.
+3. ```delimiter``` is syntactical delimiter in the format string.
#### Example usage
@@ -79,6 +85,41 @@ Will return an json object containing ```1```.
For more example usage see ```test/api_test.c```.
+### Deleter
+
+The deleter function, ```json_object_del_by_string_delimiter(3)```, deletes a value based on provided format, recommended to be used through the wrapper function ```json_object_del_by_string(2)```, defaulting the delimiter to a dot,```.```. If the specified format is not present in the object NULL is returned.
+
+```
+int json_object_del_by_string(struct json_object *src, char *fmt);
+int json_object_del_by_string_delimiter(struct json_object *src, char *fmt, const char *delimiter);
+```
+#### Arguments
+
+```src``` is a pointer to the ```struct json_object``` to traverse.
+```fmt``` is a string representing the syntax pointing to the object to be set, i.e. ```device.macaddr```, note that this syntax may contain nested objects or arrays, i.e. ```a.b[1][0].c```.
+```delimiter``` is syntactical delimiter in the format string.
+
+#### Example usage
+
+Assuming the starting json:
+
+```
+{ "nested0": { "nested1": { "integer": 1 } }, "ints": [ 1, 2, 3 ], "string": "1", "integer": 1, "obj": { "test2": "success" } }
+```
+Using the deleter:
+
+```
+ json_object_del_by_string(e->file_obj, "nested0.nested1.integer");
+```
+
+The remaining object will be:
+
+```
+{ "nested0": { "nested1": { } }, "ints": [ 1, 2, 3 ], "string": "1", "integer": 1, "obj": { "test2": "success" } }
+```
+
+For more example usage see ```test/api_test.c```.
+
### Read/Write to file
A file to json and a json to file functions have been prepared.
--
GitLab