diff options
author | Sébastien Helleu <flashcode@flashtux.org> | 2023-02-21 07:06:01 +0100 |
---|---|---|
committer | Sébastien Helleu <flashcode@flashtux.org> | 2023-03-16 20:42:18 +0100 |
commit | 66571a0b634ef28307f6d6ceef1ba29c091ca524 (patch) | |
tree | 08cc8a4eb2968952307dbfc394f51383f5dfc45e /doc/ja/weechat_plugin_api.ja.adoc | |
parent | 7b8e5b36c0e894df40642b3ce993767844edc16b (diff) | |
download | weechat-66571a0b634ef28307f6d6ceef1ba29c091ca524.zip |
core: add configuration version, add API function config_set_version
Diffstat (limited to 'doc/ja/weechat_plugin_api.ja.adoc')
-rw-r--r-- | doc/ja/weechat_plugin_api.ja.adoc | 177 |
1 files changed, 177 insertions, 0 deletions
diff --git a/doc/ja/weechat_plugin_api.ja.adoc b/doc/ja/weechat_plugin_api.ja.adoc index 52edf1b77..d66c9a1aa 100644 --- a/doc/ja/weechat_plugin_api.ja.adoc +++ b/doc/ja/weechat_plugin_api.ja.adoc @@ -6448,6 +6448,183 @@ def my_config_reload_cb(data: str, config_file: str) -> int: config_file = weechat.config_new("test", "my_config_reload_cb", "") ---- +// TRANSLATION MISSING +==== config_set_version + +_WeeChat ≥ 3.9._ + +Set configuration file version and a callback to update config sections/options +on-the-fly when the config is read. + +プロトタイプ: + +[source,c] +---- +int config_file_set_version (struct t_config_file *config_file, + int version, + struct t_hashtable *(*callback_update)(const void *pointer, + void *data, + struct t_config_file *config_file, + int version_read, + struct t_hashtable *data_read), + const void *callback_update_pointer, + void *callback_update_data); +---- + +引数: + +* _config_file_: configuration file pointer +* _version_: version, must be ≥ 2 +* _callback_update_: function called when configuration file is read, for each + section and each option, if the version read is less than the expected version, + (optional, can be NULL, see below), arguments and return value: +** _const void *pointer_: pointer +** _void *data_: pointer +** _struct t_config_file *config_file_: configuration file pointer +** _int version_read_: version read in configuration file (1 by default) +** _struct t_hashtable *data_read_: hashtable with data read from configuration file + (see below) +** return value: +*** either "data_read" pointer (hashtable completed), or pointer to a new + hashtable (created by callback, with keys and values of type "string") +* _callback_update_pointer_: pointer given to callback when it is called by + WeeChat +* _callback_update_data_: pointer given to callback when it is called by + WeeChat; if not NULL, it must have been allocated with malloc (or similar + function) and it is automatically freed when the configuration file is freed + +Update callback: + +* The callback receives a hashtable with data read from configuration file: + +[width="100%",cols="1m,2,8",options="header"] +|=== +| Key | Availability | Value +| config | Always set | Name of configuration file, without extension (eg: `weechat`) +| section | Always set | Name of section being read +| option | For option only | Name of the option +| value | For option only | Value of the option (if not NULL) +| value_null | For option only | Option as NULL value (value is always `1`) +|=== + +* The callback can update "section" for a line with a section and "option", "value" + and "value_null" for a line with an option. +* If "option" is set to empty string by the callback, the line read in + configuration file is ignored. +* Field "value_null" is set to force a NULL value for the option. + +戻り値: + +* 1 if OK, 0 if error + +C 言語での使用例: + +[source,c] +---- +struct t_hashtable * +my_config_update_cb (const void *pointer, void *data, + struct t_config_file *config_file, + int version_read, + struct t_hashtable *data_read) +{ + const char *ptr_section, *ptr_option; + + /* return now if version is already up-to-date */ + if (version_read >= 2) + return NULL; + + ptr_section = hashtable_get (data_read, "section"); + ptr_option = hashtable_get (data_read, "option"); + + /* rename section "abc" to "def" */ + if (ptr_section && !ptr_option && (strcmp (ptr_section, "abc") == 0)) + { + hashtable_set (data_read, "section", "def"); + return data_read; + } + + /* limit other changes to section "test" */ + if (!ptr_section || !ptr_option || (strcmp (ptr_section, "test") != 0)) + return NULL; + + /* rename option "test1" to "test2" */ + if (strcmp (ptr_option, "test1") == 0) + { + hashtable_set (data_read, "option", "test2"); + return data_read; + } + + /* set value to "xxx" for option "test" */ + if (strcmp (ptr_option, "test") == 0) + { + hashtable_set (data_read, "value", "xxx"); + return data_read; + } + + /* set value to NULL for option "test_null" */ + if (strcmp (ptr_option, "test_null") == 0) + { + hashtable_set (data_read, "value_null", "1"); + return data_read; + } + + /* no changes */ + return NULL; +} + +struct t_config_file *config_file = weechat_config_new ("test", NULL, NULL, NULL); +weechat_config_set_version (config_file, 2, &my_config_update_cb, NULL, NULL); +weechat_config_read (config_file); +---- + +スクリプト (Python) での使用例: + +[source,python] +---- +# プロトタイプ +def config_set_version(config_file: str, version: int, callback_update: str, callback_update_data: str) -> int: ... + +# 例 +def my_config_update_cb(data: str, config_file: str, version_read: int, data_read: Dict[str, str]) -> Dict[str, str]: + # return now if version is already up-to-date + if version_read >= 2: + return {} + + section = data_read.get("section") + option = data_read.get("option") + + # rename section "abc" to "def" + if section and not option and section == "abc": + data_read["section"] = "def" + return data_read + + # limit other changes to section "test" + if not section or not option or section != "test": + return {} + + # rename option "test1" to "test2" + if option == "test1": + data_read["option"] = "test2" + return data_read + + # set value to "xxx" for option "test" + if option == "test": + data_read["value"] = "xxx" + return data_read + + # set value to NULL for option "test_null" + if option == "test_null": + data_read["value_null"] = "1" + return data_read + + # no changes + return {} + +config_file = weechat.config_new("test", "", "") +weechat.config_set_version(config_file, 2, "my_config_update_cb", "") +weechat.config_read(config_file) +---- + ==== config_new_section _WeeChat バージョン 1.5 で更新。_ |