Unified interface for reading and writing data files in xml/json/ini and ubjson formats

Reading and writing XML/JSON/INI and UBJSON Data files in other formats

Put the abstraction into the code , Details are put into metadata .

Developing applications , Will often use various data files （ Such as configuration data and metadata ）, Common data file formats are INI、XML、JSON and UBJSON, For a complex application , Many different formats of data files may be used at the same time .

Usually , The functions that operate on these data files are different , For programmers, it is a burden of learning , It's also a burden on memory .AWTK It provides a set of unified interface functions , The same set of interface functions , You can operate data files in different formats .

1. Basic usage

After loading the data file successfully, you get a object Example , It can be used object To add it 、 modify 、 Delete and query . If you are familiar with object Usage of , That's very simple .

1.1 Reading data

The following function can read any basic type of data .

/** * @method tk_object_get_prop *  Gets the value of the specified property . * * @annotation ["scriptable"] * @param {tk_object_t*} obj object  object . * @param {const char*} name  Name of property . * @param {value_t*} v  Returns the value of the property . * * @return {ret_t}  return  RET_OK  It means success , Otherwise, it means failure . */
ret_t tk_object_get_prop(tk_object_t* obj, const char* name, value_t* v);

For ease of use , It also provides wrapper functions for common data types . Such as ：

/** * @method tk_object_get_prop_str *  Get the value of the string type of the specified property . * * @annotation ["scriptable"] * @param {tk_object_t*} obj object  object . * @param {const char*} name  Name of property . * * @return {const char*}  Returns the value of the string type of the specified property . */
const char* tk_object_get_prop_str(tk_object_t* obj, const char* name);

1.2 increase / Modifying data

The following functions can be added / Modify any basic type of data .

/** * @method tk_object_set_prop *  Set the value of the specified property . * * @annotation ["scriptable"] * @param {tk_object_t*} obj object  object . * @param {const char*} name  Name of property . * @param {value_t*} value  The value of the property . * * @return {ret_t}  return  RET_OK  It means success , Otherwise, it means failure . */
ret_t tk_object_set_prop(tk_object_t* obj, const char* name, const value_t* value);

For ease of use , It also provides wrapper functions for common data types . Such as ：

/** * @method tk_object_set_prop_str *  Set the value of the string type of the specified property . * * @annotation ["scriptable"] * @param {tk_object_t*} obj object  object . * @param {const char*} name  Name of property . * @param {const char*} value  The value of the property . * * @return {ret_t}  return  RET_OK  It means success , Otherwise, it means failure . */
ret_t tk_object_set_prop_str(tk_object_t* obj, const char* name, const char* value);

1.3 Delete data

/** * @method tk_object_remove_prop *  Delete the specified attribute . * * @annotation ["scriptable"] * @param {tk_object_t*} obj object  object . * @param {const char*} name  Name of property . * * @return {ret_t}  return  RET_OK  It means success , Otherwise, it means failure . */
ret_t tk_object_remove_prop(tk_object_t* obj, const char* name);

1.4 path The basic format of

• Configuration information is usually hierarchical , In order to access all data ,path It must also be multi-level , Use “.” Separate .

“.” Cannot be part of the name , If appear , Need to replace with other characters .

{
    
    "network" : {
     
        "eth0" : {
     
            "ip" : "192.169.0.100",
            "gateway" : "192.169.0.1",
            "mask" : "255.255.255.0"
        }   
    }   
}

In this case , To visit ip This configuration of , It can be used "network.eth0.ip":

• Access by index

During the visit , The name of each level , Index can be used instead , The format is ：[+ Indexes +], such as [0] Indicates the first item ,[2] Indicates the third item . This is not clear about the name of the case , Or traverse
All configuration , Very helpful .

• use #size Get the number of child nodes

Example ：

[wifi]
  on = 1
  name = awtk
[server]
  port = 8080
  timeout = 1.000000

In the example above ,"#size" The number of obtained groups is 2,"wifi.#size" obtain wifi The number of sub items under is 2.

• use #name Get the name of the item .

Example ：

[wifi]
  on = 1
  name = awtk
[server]
  port = 8080
  timeout = 1.000000

In the example above ,“[0].#name” Get the name of the first group as "wifi",“wifi.[0].#name” obtain wifi The name of the next item is “on”.

• use #index Get the ordinal number of the configuration item in the sibling node .

[wifi]
  on = 1
  name = awtk
[server]
  port = 8080
  timeout = 1.000000

In the example above ,“wifi.#index” obtain wifi The ordinal of is 0,“server.#index” obtain server The ordinal of is 1.

2. Advanced usage

The above function is easy to use , But when there is a large amount of data , It's better to operate directly node More efficient , If you have this requirement, you can check src/conf_io/conf_node.h Middle function , And the usage in unit testing , No more details here .

3. Open and save

At this time, you need to use functions in specific formats

3.1 JSON Format

• open

/** * @method conf_json_load *  From specified  URL  load  JSON  object . * @annotation ["constructor"] * * @param {const char*} url  route （ Usually the file path ）. * @param {bool_t} create_if_not_exist  If not, whether to create . * * @return {tk_object_t*}  Return the configuration object . */
tk_object_t* conf_json_load(const char* url, bool_t create_if_not_exist);

• preservation

/** * @method conf_json_save_as *  take  doc  Object is saved to the specified  URL. * @annotation ["static"] * * @param {tk_object_t*} obj doc  object . * @param {const char*} url  Saved in . * * @return {ret_t}  return  RET_OK  It means success , Otherwise, it means failure  */
ret_t conf_json_save_as(tk_object_t* obj, const char* url);

3.2 XML Format

• open

/** * @method conf_xml_load *  From specified  URL  load  XML  object . * * @annotation ["constructor"] * * @param {const char*} url  route （ Usually the file path ）. * @param {bool_t} create_if_not_exist  If not, whether to create . * * @return {tk_object_t*}  Return the configuration object . */
tk_object_t* conf_xml_load(const char* url, bool_t create_if_not_exist);

• preservation

/** * @method conf_xml_save_as *  take  doc  Object is saved to the specified  URL. * @annotation ["static"] * * @param {tk_object_t*} obj doc  object . * @param {const char*} url  Saved in . * * @return {ret_t}  return  RET_OK  It means success , Otherwise, it means failure  */
ret_t conf_xml_save_as(tk_object_t* obj, const char* url);

3.3 INI Format

• open

/** * @method conf_ini_load *  From specified  URL  load  INI  object . * * @annotation ["constructor"] * * @param {const char*} url  route （ Usually the file path ）. * @param {bool_t} create_if_not_exist  If not, whether to create . * * @return {tk_object_t*}  Return the configuration object . */
tk_object_t* conf_ini_load(const char* url, bool_t create_if_not_exist);

• preservation

/** * @method conf_ini_save_as *  take  doc  Object is saved to the specified  URL. * @annotation ["static"] * * @param {tk_object_t*} obj doc  object . * @param {const char*} url  Saved in . * * @return {ret_t}  return  RET_OK  It means success , Otherwise, it means failure  */
ret_t conf_ini_save_as(tk_object_t* obj, const char* url);

• 3.4 UBJSON Format

• open

/** * @method conf_ubjson_load *  From specified  URL  load  UBJSON  object . * * @annotation ["constructor"] * * @param {const char*} url  route （ Usually the file path ）. * @param {bool_t} create_if_not_exist  If not, whether to create . * * @return {tk_object_t*}  Return the configuration object . */
tk_object_t* conf_ubjson_load(const char* url, bool_t create_if_not_exist);

*  preservation 

```c
/** * @method conf_ubjson_save_as *  take  doc  Object is saved to the specified  URL. * @annotation ["static"] * * @param {tk_object_t*} obj doc  object . * @param {const char*} url  Saved in . * * @return {ret_t}  return  RET_OK  It means success , Otherwise, it means failure  */
ret_t conf_ubjson_save_as(tk_object_t* obj, const char* url);

Complete example

#include "conf_io/conf_json.h"

void demo_conf_json(c) {
    
  tk_object_t* doc = conf_json_load("./test.json", TRUE);
  tk_object_set_prop_str(doc, "name", "awtk");
  tk_object_set_prop_int(doc, "age", 100);
  conf_json_save_as(doc, "./test.json");
  TK_OBJECT_UNREF(doc);
  
  doc = conf_json_load("./test.json", TRUE);

  log_debug("name:%s\n", tk_object_get_prop_str(doc, "name"));
  log_debug("age:%d\n", tk_object_get_prop_int(doc, "age", 0));
  TK_OBJECT_UNREF(doc);
}

The corresponding data file is ：

{
    
    "name" : "awtk",
    "age" : 100 
}