summaryrefslogtreecommitdiff
path: root/doc/en
diff options
context:
space:
mode:
authorSebastien Helleu <flashcode@flashtux.org>2009-10-09 15:46:29 +0200
committerSebastien Helleu <flashcode@flashtux.org>2009-10-09 15:46:29 +0200
commitbfb9ab6a2a2c744f154b6411d436a19ebf8e9c4f (patch)
treefbb3af22816d42aa93b64e69b617c6538e08b827 /doc/en
parent5535ec5f46783d00ca2172c377c515658be569ce (diff)
downloadweechat-bfb9ab6a2a2c744f154b6411d436a19ebf8e9c4f.zip
Add script prototypes and examples in plugin API reference
Diffstat (limited to 'doc/en')
-rw-r--r--doc/en/autogen/plugin_api/infolists.txt10
-rw-r--r--doc/en/weechat_plugin_api.en.txt2344
-rw-r--r--doc/en/weechat_scripting.en.txt119
3 files changed, 2198 insertions, 275 deletions
diff --git a/doc/en/autogen/plugin_api/infolists.txt b/doc/en/autogen/plugin_api/infolists.txt
index f0ad68c73..fb925d05b 100644
--- a/doc/en/autogen/plugin_api/infolists.txt
+++ b/doc/en/autogen/plugin_api/infolists.txt
@@ -13,17 +13,17 @@
| logger | logger_buffer | list of logger buffers
-| lua | lua_script | list of lua scripts
+| lua | lua_script | liste des scripts lua
-| perl | perl_script | list of perl scripts
+| perl | perl_script | liste des scripts perl
-| python | python_script | list of python scripts
+| python | python_script | liste des scripts python
| relay | relay | list of relay clients
-| ruby | ruby_script | list of ruby scripts
+| ruby | ruby_script | liste des scripts ruby
-| tcl | tcl_script | list of tcl scripts
+| tcl | tcl_script | liste des scripts tcl
| weechat | bar | list of bars
diff --git a/doc/en/weechat_plugin_api.en.txt b/doc/en/weechat_plugin_api.en.txt
index f7bab03f9..cda8964ae 100644
--- a/doc/en/weechat_plugin_api.en.txt
+++ b/doc/en/weechat_plugin_api.en.txt
@@ -208,9 +208,20 @@ weechat_plugin_end (struct t_weechat_plugin *plugin)
}
----------------------------------------
-[[c_plugin_api]]
-C plugin API
-------------
+[[plugin_api]]
+Plugin API
+----------
+
+Following chapters describe functions in API, sorted by category.
+
+For each function, we give:
+
+* description of function,
+* C prototype,
+* detail of arguments,
+* return value,
+* C example,
+* example in Python script (syntax for other scripting languages is similar).
[[plugins]]
Plugins
@@ -238,13 +249,25 @@ Return value:
* name of plugin, "core" for WeeChat core (if plugin pointer is NULL)
-Example:
+C example:
[source,C]
----------------------------------------
const char *name = weechat_plugin_get_name (plugin);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+name = weechat.plugin_get_name(plugin)
+
+# example
+plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin")
+name = weechat.plugin_get_name(plugin)
+----------------------------------------
+
[[strings]]
Strings
~~~~~~~
@@ -270,13 +293,24 @@ Arguments:
* 'charset': new charset to use
-Example:
+C example:
[source,C]
----------------------------------------
weechat_charset_set (plugin, "iso-8859-1");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.charset_set(charset)
+
+# example
+weechat.charset_set("iso-8859-1")
+----------------------------------------
+
weechat_iconv_to_internal
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -298,7 +332,7 @@ Return value:
* converted string (must be freed by calling "free" after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -307,6 +341,17 @@ char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à"
free (str);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+str = weechat.iconv_to_internal(charset, string)
+
+# example
+str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à")
+----------------------------------------
+
weechat_iconv_from_internal
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -328,7 +373,7 @@ Return value:
* converted string (must be freed by calling "free" after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -337,6 +382,17 @@ char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");
free (str);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+str = weechat.iconv_from_internal(charset, string)
+
+# example
+str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à")
+----------------------------------------
+
weechat_gettext
^^^^^^^^^^^^^^^
@@ -357,11 +413,22 @@ Return value:
* translated string
-Example:
+C example:
[source,C]
----------------------------------------
-char *str = weechat_gettext ("hello !");
+char *str = weechat_gettext ("hello");
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+str = weechat.gettext(string)
+
+# example
+str = weechat.gettext("hello")
----------------------------------------
weechat_ngettext
@@ -389,13 +456,25 @@ Return value:
* translated string
-Example:
+C example:
[source,C]
----------------------------------------
char *str = weechat_ngettext ("file", "files", num_files);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+str = weechat.ngettext(string, plural, count)
+
+# example
+num_files = 2
+str = weechat.ngettext("file", "files", num_files)
+----------------------------------------
+
weechat_strndup
^^^^^^^^^^^^^^^
@@ -417,7 +496,7 @@ Return value:
* duplicated string (must be freed by calling "free" after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -442,7 +521,7 @@ Arguments:
* 'string': string to convert
-Example:
+C example:
[source,C]
----------------------------------------
@@ -466,7 +545,7 @@ Arguments:
* 'string': string to convert
-Example:
+C example:
[source,C]
----------------------------------------
@@ -498,7 +577,7 @@ Return value:
** zero if string1 == string2
** positive if string1 > string2
-Example:
+C example:
[source,C]
----------------------------------------
@@ -534,7 +613,7 @@ Return value:
** zero if string1 == string2
** positive if string1 > string2
-Example:
+C example:
[source,C]
----------------------------------------
@@ -562,7 +641,7 @@ Return value:
* pointer to string found, or NULL if not found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -592,7 +671,7 @@ Return value:
* 1 if string matches mask, otherwise 0
-Example:
+C example:
[source,C]
----------------------------------------
@@ -626,7 +705,7 @@ Return value:
* string with 'search' replaced by 'replace' (must be freed by calling "free"
after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -658,7 +737,7 @@ Return value:
* string without quotes at beginning/end (must be freed by calling "free"
after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -692,7 +771,7 @@ Return value:
* stripped string (must be freed by calling "free" after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -723,7 +802,7 @@ Return value:
* 1 if string has one or more highlights, otherwise 0
-Example:
+C example:
[source,C]
----------------------------------------
@@ -751,7 +830,7 @@ Return value:
* regular expression, as string (must be freed by calling "free" after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -830,7 +909,7 @@ Arguments:
* 'split_string': string split by function <<_weechat_string_split>>
-Example:
+C example:
[source,C]
----------------------------------------
@@ -863,7 +942,7 @@ Return value:
* string built with split string (must be freed by calling "free" after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -899,7 +978,7 @@ Return value:
* array of strings, NULL if problem (must be freed by calling
<<_weechat_free_split_command>> after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -926,7 +1005,7 @@ Arguments:
* 'split_command': command split by <<_weechat_string_split_command>>
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1018,6 +1097,17 @@ char *str = weechat_string_remove_color (my_string2, "?");
free (str);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+str = weechat.string_remove_color(string, replacement)
+
+# example
+str = weechat.string_remove_color(my_string, "?")
+----------------------------------------
+
[[utf-8]]
UTF-8
~~~~~
@@ -1044,7 +1134,7 @@ Return value:
* 1 if string has 8-bits chars, 0 if only 7-bits chars
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1076,7 +1166,7 @@ Return value:
* 1 if UTF-8 string is valid, otherwise 0
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1108,7 +1198,7 @@ Arguments:
* 'string': string
* 'replacement': replacement char for invalid chars
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1137,7 +1227,7 @@ Return value:
* pointer to previous UTF-8 char, NULL if not found (start of string reached)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1164,7 +1254,7 @@ Return value:
* pointer to next UTF-8 char, NULL if not found (end of string reached)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1191,7 +1281,7 @@ Return value:
* UTF-8 char size (in bytes)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1218,7 +1308,7 @@ Return value:
* UTF-8 string length (number of UTF-8 chars)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1246,7 +1336,7 @@ Return value:
* UTF-8 string length (number of UTF-8 chars)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1273,7 +1363,7 @@ Return value:
* number of chars needed on screen to display UTF-8 string
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1304,7 +1394,7 @@ Return value:
** zero if char1 == char2
** positive if char1 > char2
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1331,7 +1421,7 @@ Return value:
* number of chars needed on screen to display UTF-8 char
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1359,7 +1449,7 @@ Return value:
* pointer to string, N chars after (NULL if it's not reachable)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1388,7 +1478,7 @@ Return value:
* real potision (in bytes)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1416,7 +1506,7 @@ Return value:
* position (number of chars)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1444,7 +1534,7 @@ Return value:
* duplicated string (must be freed by calling "free" after use)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1480,16 +1570,27 @@ Return value:
* 1 if directory was successfully created, 0 if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
-if (!weechat_mkdir_home ("temp"))
+if (!weechat_mkdir_home ("temp", 0755))
{
/* error */
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.mkdir_home(directory, mode)
+
+# example
+weechat.mkdir_home("temp", 0755)
+----------------------------------------
+
weechat_mkdir
^^^^^^^^^^^^^
@@ -1511,16 +1612,27 @@ Return value:
* 1 if directory was successfully created, 0 if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
-if (!weechat_mkdir ("/tmp/mydir"))
+if (!weechat_mkdir ("/tmp/mydir", 0755))
{
/* error */
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.mkdir(directory, mode)
+
+# example
+weechat.mkdir("/tmp/mydir", 0755)
+----------------------------------------
+
weechat_mkdir_parents
^^^^^^^^^^^^^^^^^^^^^
@@ -1542,16 +1654,27 @@ Return value:
* 1 if directory was successfully created, 0 if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
-if (!weechat_mkdir_parents ("/tmp/my/dir"))
+if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
{
/* error */
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.mkdir_parents(directory, mode)
+
+# example
+weechat.mkdir_parents("/tmp/my/dir", 0755)
+----------------------------------------
+
weechat_exec_on_files
^^^^^^^^^^^^^^^^^^^^^
@@ -1577,7 +1700,7 @@ Arguments:
** 'void *data': pointer
** 'const char *filename': filename found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1618,7 +1741,7 @@ Return value:
* zero if tv1 == tv2
* +1 if tv1 > tv2
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1649,7 +1772,7 @@ Return value:
* difference in milliseconds
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1673,7 +1796,7 @@ Arguments:
* 'tv': timeval structure
* 'interval': interval (in milliseconds)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1702,13 +1825,24 @@ Return value:
* pointer to new list
-Example:
+C example:
[source,C]
----------------------------------------
struct t_weelist *list = weechat_list_new ();
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+list = weechat.list_new()
+
+# example
+list = weechat.list_new()
+----------------------------------------
+
weechat_list_add
^^^^^^^^^^^^^^^^
@@ -1738,7 +1872,7 @@ Return value:
* pointer to new item
-Example:
+C example:
[source,C]
----------------------------------------
@@ -1746,6 +1880,17 @@ struct t_weelist_item *my_item =
weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+item = weechat.list_add(list, data, where, user_data)
+
+# example
+item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "")
+----------------------------------------
+
weechat_list_search
^^^^^^^^^^^^^^^^^^^
@@ -1768,13 +1913,24 @@ Return value:
* pointer to item found, NULL if item was not found
-Example:
+C example:
[source,C]
----------------------------------------
struct t_weelist_item *item = weechat_list_search (list, "my data");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+item = weechat.list_search(list, data)
+
+# example
+item = weechat.list_search(list, "my data")
+----------------------------------------
+
weechat_list_casesearch
^^^^^^^^^^^^^^^^^^^^^^^
@@ -1797,13 +1953,24 @@ Return value:
* pointer to item found, NULL if item was not found
-Example:
+C example:
[source,C]
----------------------------------------
struct t_weelist_item *item = weechat_list_casesearch (list, "my data");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+item = weechat.list_casesearch(list, data)
+
+# example
+item = weechat.list_casesearch(list, "my data")
+----------------------------------------
+
weechat_list_get
^^^^^^^^^^^^^^^^
@@ -1826,13 +1993,24 @@ Return value:
* pointer to item found, NULL if item was not found
-Example:
+C example:
[source,C]
----------------------------------------
struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+item = weechat.list_get(list, position)
+
+# example
+item = weechat.list_get(list, 0)
+----------------------------------------
+
weechat_list_set
^^^^^^^^^^^^^^^^
@@ -1850,13 +2028,24 @@ Arguments:
* 'item': item pointer
* 'value': new value for item
-Example:
+C example:
[source,C]
----------------------------------------
weechat_list_set (item, "new data");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.list_set(item, value)
+
+# example
+weechat.list_set(item, "new data")
+----------------------------------------
+
weechat_list_next
^^^^^^^^^^^^^^^^^
@@ -1877,11 +2066,22 @@ Return value:
* pointer to next item, NULL if pointer was last item in list
-Example:
+C example:
[source,C]
----------------------------------------
-struct t_weelist_item *next_item = weechat_list_next_item (item);
+struct t_weelist_item *next_item = weechat_list_next (item);
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+item = weechat.list_next(item)
+
+# example
+item = weechat.list_next(item)
----------------------------------------
weechat_list_prev
@@ -1904,11 +2104,22 @@ Return value:
* pointer to previous item, NULL if pointer was last item in list
-Example:
+C example:
[source,C]
----------------------------------------
-struct t_weelist_item *prev_item = weechat_list_prev_item (item);
+struct t_weelist_item *prev_item = weechat_list_prev (item);
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+item = weechat.list_prev(item)
+
+# example
+item = weechat.list_prev(item)
----------------------------------------
weechat_list_string
@@ -1931,11 +2142,22 @@ Return value:
* string value of item
-Example:
+C example:
[source,C]
----------------------------------------
-char *value = weechat_list_string (item);
+weechat_printf (NULL, "value of item: %s", weechat_list_string (item));
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.list_string(item)
+
+# example
+weechat.prnt("", "value of item: %s" % weechat.list_string(item))
----------------------------------------
weechat_list_size
@@ -1958,11 +2180,22 @@ Return value:
* size of list (number of items), 0 if list is empty
-Example:
+C example:
[source,C]
----------------------------------------
-int size = weechat_list_size (list);
+weechat_printf (NULL, "size of list: %d", weechat_list_size (list));
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+size = weechat.list_size(list)
+
+# example
+weechat.prnt("", "size of list: %d" % weechat.list_size(list))
----------------------------------------
weechat_list_remove
@@ -1983,13 +2216,24 @@ Arguments:
* 'weelist': list pointer
* 'item': item pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_list_remove (list, item);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.list_remove(list, item)
+
+# example
+weechat.list_remove(list, item)
+----------------------------------------
+
weechat_list_remove_all
^^^^^^^^^^^^^^^^^^^^^^^
@@ -2006,13 +2250,24 @@ Arguments:
* 'weelist': list pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_list_remove_all (list);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.list_remove_all(list)
+
+# example
+weechat.list_remove_all(list)
+----------------------------------------
+
weechat_list_free
^^^^^^^^^^^^^^^^^
@@ -2029,13 +2284,24 @@ Arguments:
* 'weelist': list pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_list_free (list);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.list_free(list)
+
+# example
+weechat.list_free(list)
+----------------------------------------
+
[[configuration_files]]
Configuration files
~~~~~~~~~~~~~~~~~~~
@@ -2077,7 +2343,7 @@ function <<_weechat_write_config>>. You should call this function only after
adding some sections (with <<_weechat_config_new_section>>) and options (with
<<_weechat_config_new_option>>).
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2094,6 +2360,21 @@ struct t_config_file *config_file = weechat_config_new ("test",
NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+config_file = weechat.config_new(name, calback_reload, callback_reload_data)
+
+# example
+def my_config_reload_cb(data, config_file):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+config_file = weechat.config_new("test", "my_config_reload_cb", "")
+----------------------------------------
+
weechat_config_new_section
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2191,7 +2472,7 @@ Return value:
* pointer to new section in configuration file, NULL if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2263,6 +2544,47 @@ struct t_config_section *new_section2 =
&my_section_delete_option_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+section = weechat.config_new_section(config_file, name,
+ user_can_add_options, user_can_delete_options,
+ callback_read, callback_read_data,
+ callback_write, callback_write_data,
+ callback_create_option, callback_create_option_data,
+ callback_delete_option, callback_delete_option_data)
+
+# example
+def my_section_read_cb(data, config_file, section, option_name, value):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+def my_section_write_cb(data, config_file, section_name):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+def my_section_write_default_cb(data, config_file, section_name):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+def my_section_create_option_cb(data, config_file, section, option_name, value):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+def my_section_delete_option_cb(data, config_file, section, option):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+section = weechat.config_new_section(config_file, "section1", 1, 1,
+ "my_section_read_cb", "",
+ "my_section_write_cb", "",
+ "my_section_write_default_cb", "",
+ "my_section_create_option_cb", "",
+ "my_section_delete_option_cb", "")
+----------------------------------------
+
weechat_config_search_section
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2286,7 +2608,7 @@ Return value:
* pointer to section found, NULL if section was not found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2294,6 +2616,17 @@ struct t_config_section *section = weechat_config_search_section (config_file,
"section");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+section = weechat.config_search_section(config_file, section_name)
+
+# example
+section = weechat.config_search_section(config_file, "section")
+----------------------------------------
+
weechat_config_new_option
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2370,14 +2703,14 @@ Return value:
* pointer to new option in section, NULL if an error
-Example:
+C example:
[source,C]
----------------------------------------
/* boolean */
struct t_config_option *option1 =
- weechat_config_new_option (config_file, section,
- "option1", "My option, type boolean"
+ weechat_config_new_option (config_file, section, "option1", "boolean",
+ "My option, type boolean"
NULL, /* string values */
0, 0, /* min, max */
"on", /* default */
@@ -2389,8 +2722,8 @@ struct t_config_option *option1 =
/* integer */
struct t_config_option *option2 =
- weechat_config_new_option (config_file, section,
- "option2", "My option, type integer"
+ weechat_config_new_option (config_file, section, "option2", "integer",
+ "My option, type integer"
NULL, /* string values */
0, 100, /* min, max */
"15", /* default */
@@ -2402,8 +2735,8 @@ struct t_config_option *option2 =
/* integer (with string values) */
struct t_config_option *option3 =
- weechat_config_new_option (config_file, section,
- "option3", "My option, type integer (with string values)"
+ weechat_config_new_option (config_file, section, "option3", "integer",
+ "My option, type integer (with string values)"
"top|bottom|left|right", /* string values */
0, 0, /* min, max */
"bottom", /* default */
@@ -2415,8 +2748,8 @@ struct t_config_option *option3 =
/* string */
struct t_config_option *option4 =
- weechat_config_new_option (config_file, section,
- "option4", "My option, type string"
+ weechat_config_new_option (config_file, section, "option4", "string",
+ "My option, type string"
NULL, /* string values */
0, 0, /* min, max */
"test", /* default */
@@ -2428,8 +2761,8 @@ struct t_config_option *option4 =
/* color */
struct t_config_option *option5 =
- weechat_config_new_option (config_file, section,
- "option5", "My option, type color"
+ weechat_config_new_option (config_file, section, "option5", "color",
+ "My option, type color"
NULL, /* string values */
0, 0, /* min, max */
"lightblue", /* default */
@@ -2440,6 +2773,67 @@ struct t_config_option *option5 =
NULL, NULL); /* delete callback */
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+option = weechat.config_new_option(config_file, section, name, type, description,
+ string_values, min, max, default_value, value, null_value_allowed,
+ callback_check_value, callback_check_value_data,
+ callback_change, callback_change_data,
+ callback_delete, callback_delete_data)
+
+# example
+def option4_check_value_cb(data, option, value):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+def option4_change_cb(data, option):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+def option4_delete_cb(data, option):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+option1 = weechat.config_new_option(config_file, section, "option1", "boolean",
+ "My option, type boolean",
+ "", 0, 0, "on", "on", 0,
+ "", "",
+ "", "",
+ "", "")
+
+option2 = weechat.config_new_option(config_file, section, "option2", "integer",
+ "My option, type integer",
+ "", 0, 100, "15", "15", 0,
+ "", "",
+ "", "",
+ "", "")
+
+option3 = weechat.config_new_option(config_file, section, "option3", "integer",
+ "My option, type integer (with string values)",
+ "top|bottom|left|right",
+ 0, 0, "bottom", "bottom", 0,
+ "", "",
+ "", "",
+ "", "")
+
+option4 = weechat.config_new_option(config_file, section, "option4", "string",
+ "My option, type string",
+ "", 0, 0, "test", "test", 1,
+ "option4_check_value_cb", ""
+ "option4_change_cb", "",
+ "option4_delete_cb", "")
+
+option5 = weechat.config_new_option(config_file, section, "option5", "color",
+ "My option, type color",
+ "", 0, 100, "lightblue", "lightblue", 0,
+ "", "",
+ "", "",
+ "", "")
+----------------------------------------
+
weechat_config_search_option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2465,7 +2859,7 @@ Return value:
* pointer to option found, NULL if option was not found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2473,6 +2867,17 @@ struct t_config_option *option =
weechat_config_search_option (config_file, section, "option");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+option = weechat.config_search_option(config_file, section, option_name)
+
+# example
+option = weechat.config_search_option(config_file, section, "option")
+----------------------------------------
+
weechat_config_search_with_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2498,7 +2903,7 @@ Arguments:
* 'option': pointer to an option pointer, will be set to option pointer, if
found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2541,7 +2946,7 @@ Return value:
* 1 if text is "true" ("on", "yes", "y", "true", "t", "1")
* 0 if text is "false" ("off", "no", "n", "false", "f", "0")
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2555,6 +2960,18 @@ else
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_string_to_boolean(text)
+
+# example
+if weechat.config_string_to_boolean(text):
+ # ...
+----------------------------------------
+
weechat_config_option_reset
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2580,7 +2997,7 @@ Return value:
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2598,6 +3015,23 @@ switch (weechat_config_option_reset (option, 1))
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.config_option_reset(option, run_callback)
+
+# example
+rc = weechat.config_option_reset(option, 1)
+if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
+ # ...
+----------------------------------------
+
weechat_config_option_set
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2624,7 +3058,7 @@ Return value:
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2642,6 +3076,23 @@ switch (weechat_config_option_set (option, "new_value", 1))
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.config_option_set(option, value, run_callback)
+
+# example
+rc = weechat.config_option_set(option, "new_value", 1)
+if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
+ # ...
+----------------------------------------
+
weechat_config_option_set_null
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2671,7 +3122,7 @@ Return value:
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' if value was not changed
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2689,6 +3140,23 @@ switch (weechat_config_option_set_null (option, 1))
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.config_option_set_null(option, run_callback)
+
+# example
+rc = weechat.config_option_set_null(option, 1)
+if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
+ # ...
+----------------------------------------
+
weechat_config_option_unset
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2712,7 +3180,7 @@ Return value:
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' if option has been removed
* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2733,6 +3201,25 @@ switch (weechat_config_option_unset (option))
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.config_option_unset(option)
+
+# example
+rc = weechat.config_option_unset(option)
+if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
+ # ...
+----------------------------------------
+
weechat_config_option_rename
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2751,13 +3238,24 @@ Arguments:
* 'option': option pointer
* 'new_name': new name for option
-Example:
+C example:
[source,C]
----------------------------------------
weechat_config_option_rename (option, "new_name");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.config_option_rename(option, new_name)
+
+# example
+weechat.config_option_rename(option, "new_name")
+----------------------------------------
+
weechat_config_option_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2792,7 +3290,7 @@ Return value:
* pointer to property asked
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2820,7 +3318,7 @@ Return value:
* 1 if value of option is "null"
* 0 if value of option is not "null"
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2834,6 +3332,65 @@ else
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.config_option_is_null(option)
+
+# example
+if weechat.config_option_is_null(option):
+ # ...
+----------------------------------------
+
+weechat_config_option_default_is_null
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Check if default value for an option is "null" (undefined value).
+
+Prototype:
+
+[source,C]
+----------------------------------------
+int weechat_config_option_default_is_null (struct t_config_option *option);
+----------------------------------------
+
+Arguments:
+
+* 'option': option pointer
+
+Return value:
+
+* 1 if default value of option is "null"
+* 0 if default value of option is not "null"
+
+C example:
+
+[source,C]
+----------------------------------------
+if (weechat_config_option_default_is_null (option))
+{
+ /* default value is "null" */
+}
+else
+{
+ /* default value is not "null" */
+}
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.config_option_default_is_null(option)
+
+# example
+if weechat.config_option_default_is_null(option):
+ # ...
+----------------------------------------
+
weechat_config_boolean
^^^^^^^^^^^^^^^^^^^^^^
@@ -2854,7 +3411,7 @@ Return value:
* boolean value of option (0 or 1)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2868,6 +3425,18 @@ else
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_option_boolean(option)
+
+# example
+if weechat.config_option_boolean(option):
+ # ...
+----------------------------------------
+
weechat_config_boolean_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2888,7 +3457,7 @@ Return value:
* default boolean value of option (0 or 1)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -2902,6 +3471,18 @@ else
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_option_boolean_default(option)
+
+# example
+if weechat.config_option_boolean_default(option):
+ # ...
+----------------------------------------
+
weechat_config_integer
^^^^^^^^^^^^^^^^^^^^^^
@@ -2922,13 +3503,25 @@ Return value:
* integer value of option
-Example:
+C example:
[source,C]
----------------------------------------
int value = weechat_config_integer (option);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_option_integer(option)
+
+# example
+if weechat.config_option_integer(option):
+ # ...
+----------------------------------------
+
weechat_config_integer_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2949,13 +3542,25 @@ Return value:
* default integer value of option
-Example:
+C example:
[source,C]
----------------------------------------
int value = weechat_config_integer_default (option);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_option_integer_default(option)
+
+# example
+if weechat.config_option_integer_default(option):
+ # ...
+----------------------------------------
+
weechat_config_string
^^^^^^^^^^^^^^^^^^^^^
@@ -2976,13 +3581,24 @@ Return value:
* string value of option
-Example:
+C example:
[source,C]
----------------------------------------
const char *value = weechat_config_string (option);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_option_string(option)
+
+# example
+value = weechat.config_option_string(option):
+----------------------------------------
+
weechat_config_string_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3003,13 +3619,24 @@ Return value:
* default string value of option
-Example:
+C example:
[source,C]
----------------------------------------
const char *value = weechat_config_string_default (option);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_option_string_default(option)
+
+# example
+value = weechat.config_option_string_default(option):
+----------------------------------------
+
weechat_config_color
^^^^^^^^^^^^^^^^^^^^
@@ -3030,13 +3657,24 @@ Return value:
* color value of option (string with name of color)
-Example:
+C example:
[source,C]
----------------------------------------
const char *color = weechat_config_color (option);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_option_color(option)
+
+# example
+value = weechat.config_option_color(option):
+----------------------------------------
+
weechat_config_color_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3057,13 +3695,24 @@ Return value:
* default color value of option (string with name of color)
-Example:
+C example:
[source,C]
----------------------------------------
const char *color = weechat_config_color_default (option);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_option_color_default(option)
+
+# example
+value = weechat.config_option_color_default(option):
+----------------------------------------
+
weechat_config_write_option
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3083,7 +3732,7 @@ Arguments:
* 'config_file': configuration file pointer
* 'option': option pointer
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3099,6 +3748,20 @@ my_section_write_cb (void *data, struct t_config_file *config_file,
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.config_write_option(config_file, option)
+
+# example
+def my_section_write_cb(data, config_file, section_name):
+ weechat.config_write_line(config_file, "my_section", "")
+ weechat.config_write_option(config_file, option)
+ return weechat.WEECHAT_RC_OK
+----------------------------------------
+
weechat_config_write_line
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3121,7 +3784,7 @@ Arguments:
* 'value': value (if NULL, then line with section name is written, for
example: "[section]")
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3138,6 +3801,20 @@ my_section_write_cb (void *data, struct t_config_file *config_file,
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.config_write_line(config_file, option_name, value)
+
+# example
+def my_section_write_cb(data, config_file, section_name):
+ weechat.config_write_line(config_file, "my_section", "")
+ weechat.config_write_line(config_file, "option", "value")
+ return weechat.WEECHAT_RC_OK
+----------------------------------------
+
weechat_config_write
^^^^^^^^^^^^^^^^^^^^
@@ -3160,7 +3837,7 @@ Return value:
* 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR' if there was not enough memory
* 'WEECHAT_CONFIG_WRITE_ERROR' if another error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3178,6 +3855,23 @@ switch (weechat_config_write (config_file))
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.config_write(config_file)
+
+# example
+rc = weechat.config_write(config_file)
+if rc == weechat.WEECHAT_CONFIG_WRITE_OK:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR:
+ # ...
+----------------------------------------
+
weechat_config_read
^^^^^^^^^^^^^^^^^^^
@@ -3200,7 +3894,7 @@ Return value:
* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' if there was not enough memory
* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' if file was not found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3218,6 +3912,23 @@ switch (weechat_config_read (config_file))
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.config_read(config_file)
+
+# example
+rc = weechat.config_read(config_file)
+if rc == weechat.WEECHAT_CONFIG_READ_OK:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
+ # ...
+----------------------------------------
+
weechat_config_reload
^^^^^^^^^^^^^^^^^^^^^
@@ -3240,7 +3951,7 @@ Return value:
* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' if there was not enough memory
* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' if file was not found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3258,6 +3969,23 @@ switch (weechat_config_reload (config_file))
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.config_reload(config_file)
+
+# example
+rc = weechat.config_reload(config_file)
+if rc == weechat.WEECHAT_CONFIG_READ_OK:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
+ # ...
+----------------------------------------
+
weechat_config_option_free
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3274,13 +4002,24 @@ Arguments:
* 'option': option pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_config_option_free (option);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.config_option_free(option)
+
+# example
+weechat.config_option_free(option)
+----------------------------------------
+
weechat_config_section_free_options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3297,13 +4036,24 @@ Arguments:
* 'section': section pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_config_section_free_options (section);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.config_section_free_options(section)
+
+# example
+weechat.config_section_free_options(section)
+----------------------------------------
+
weechat_config_section_free
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3320,13 +4070,24 @@ Arguments:
* 'section': section pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_config_section_free (section);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.config_section_free(section)
+
+# example
+weechat.config_section_free(section)
+----------------------------------------
+
weechat_config_free
^^^^^^^^^^^^^^^^^^^
@@ -3343,13 +4104,24 @@ Arguments:
* 'config_file': configuration file pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_config_free (config_file);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.config_free(config_file)
+
+# example
+weechat.config_free(config_file)
+----------------------------------------
+
weechat_config_get
^^^^^^^^^^^^^^^^^^
@@ -3370,13 +4142,24 @@ Return value:
* pointer to option found, NULL if option was not found
-Example:
+C example:
[source,C]
----------------------------------------
struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+option = weechat.config_get(option_name)
+
+# example
+option = weechat.config_get("weechat.look.item_time_format")
+----------------------------------------
+
weechat_config_get_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3398,7 +4181,7 @@ Return value:
* value of option found, NULL if option was not found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3407,6 +4190,17 @@ Example:
char *value = weechat_config_get_plugin ("option");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_get_plugin(option_name)
+
+# example
+value = weechat.config_get_plugin("option")
+----------------------------------------
+
weechat_config_is_set_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3428,7 +4222,7 @@ Return value:
* 1 if option is set, 0 if option does not exist
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3442,6 +4236,22 @@ else
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.config_is_set_plugin(option_name)
+
+# example
+if weechat.config_is_set_plugin("option"):
+ # option is set
+ # ...
+else:
+ # option does not exist
+ # ...
+----------------------------------------
+
weechat_config_set_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3467,7 +4277,7 @@ Return value:
* 'WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND' if option was not found
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' if other error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3488,6 +4298,25 @@ switch (weechat_config_set_plugin ("option", "test_value"))
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.config_set_plugin(option_name, value)
+
+# example
+rc = weechat.config_is_set_plugin("option", "test_value")
+if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
+ # ...
+----------------------------------------
+
weechat_config_unset_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3512,7 +4341,7 @@ Return value:
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' if option has been removed
* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3533,6 +4362,25 @@ switch (weechat_config_unset_plugin ("option"))
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.config_unset_plugin(option_name)
+
+# example
+rc = weechat.config_unset_plugin("option")
+if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
+ # ...
+elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
+ # ...
+----------------------------------------
+
[[display]]
Display
~~~~~~~
@@ -3555,7 +4403,7 @@ Arguments:
* 'prefix': name of prefix:
-[width="60%",cols="^2,^1,^2,5",options="header"]
+[width="70%",cols="^2,^1,^3,5",options="header"]
|========================================
| Prefix | Value | Color | Description
| 'error' | `=!=` | yellow | error message
@@ -3573,13 +4421,24 @@ Return value:
* prefix value (string with prefix and color codes), empty string if prefix is
not found
-Example:
+C example:
[source,C]
----------------------------------------
weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.prefix(prefix)
+
+# example
+weechat.prnt("", "%sThis is an error..." % weechat.prefix("error"))
+----------------------------------------
+
weechat_color
^^^^^^^^^^^^^
@@ -3615,16 +4474,28 @@ Return value:
* string with color code, or a "reset color" code if color is not found
-Example:
+C example:
[source,C]
----------------------------------------
-weechat_printf (NULL, "Color: %sblue %schat default %syellow on red",
+weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red",
weechat_color ("blue"),
weechat_color ("chat"),
weechat_color ("yellow,red"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.color(color_name)
+
+# example
+weechat.prnt("", "%sColor: %sblue %sdefault color %syellow on red"
+ % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))
+----------------------------------------
+
weechat_printf
^^^^^^^^^^^^^^
@@ -3642,7 +4513,7 @@ Arguments:
* 'buffer': buffer pointer, if NULL, message is displayed on WeeChat buffer
* 'message': message to display
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3650,6 +4521,21 @@ weechat_printf (NULL, "Hello on WeeChat buffer");
weechat_printf (buffer, "Hello on this buffer");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.prnt(buffer, message)
+
+# example
+weechat.prnt("", "Hello on WeeChat buffer")
+weechat.prnt(buffer, "Hello on this buffer")
+----------------------------------------
+
+[NOTE]
+Function is called "print" in scripts ("prnt" in Python).
+
weechat_printf_date
^^^^^^^^^^^^^^^^^^^
@@ -3669,7 +4555,7 @@ Arguments:
* 'date': date for message
* 'message': message to display
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3695,7 +4581,7 @@ Arguments:
* 'tags': comma separated list of tags
* 'message': message to display
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3723,7 +4609,7 @@ Arguments:
* 'tags': comma separated list of tags
* 'message': message to display
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3731,6 +4617,22 @@ weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
"Message 2 minutes ago, with a tag 'notify_message'");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.prnt_date_tags(buffer, date, tags, message)
+
+# example
+time = int(time.time())
+weechat.prnt_date_tags("", time - 120, "notify_message",
+ "Message 2 minutes ago, with a tag 'notify_message'")
+----------------------------------------
+
+[NOTE]
+Function is called "print_date_tags" in scripts ("prnt_date_tags" in Python).
+
weechat_printf_y
^^^^^^^^^^^^^^^^
@@ -3750,13 +4652,27 @@ Arguments:
* 'y': line number (first line is 0)
* 'message': message to display
-Example:
+C example:
[source,C]
----------------------------------------
weechat_printf_y (buffer, 2, "My message on third line");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.prnt_y(buffer, y, message)
+
+# example
+weechat.prnt_y("", 2, "My message on third line")
+----------------------------------------
+
+[NOTE]
+Function is called "print_y" in scripts ("prnt_y" in Python).
+
weechat_log_printf
^^^^^^^^^^^^^^^^^^
@@ -3773,13 +4689,27 @@ Arguments:
* 'message': message to write
-Example:
+C example:
[source,C]
----------------------------------------
weechat_log_printf ("My message in log file");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.log_print(message)
+
+# example
+weechat.log_print("My message in log file")
+----------------------------------------
+
+[NOTE]
+Function is called "log_print" in scripts.
+
[[hooks]]
Hooks
~~~~~
@@ -3800,7 +4730,8 @@ struct t_hook *weechat_hook_command (const char *command,
const char *completion,
int (*callback)(void *data,
struct t_gui_buffer *buffer,
- int argc, char **argv,
+ int argc,
+ char **argv,
char **argv_eol),
void *callback_data);
----------------------------------------
@@ -3837,7 +4768,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3886,6 +4817,33 @@ argv_eol contain following values:
** 'argv_eol[1]' == "def ghi"
** 'argv_eol[2]' == "ghi"
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_command(command, description, args, args_description,
+ completion, callback, callback_data)
+
+# example
+def my_command_cb(data, buffer, args):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+hook = weechat.hook_command("myfilter", "description of myfilter",
+ "[list] | [enable|disable|toggle [name]] | "
+ "[add name plugin.buffer tags regex] | "
+ "[del name|-all]",
+ "description of arguments...",
+ "list"
+ " || enable %(filters_names)"
+ " || disable %(filters_names)"
+ " || toggle %(filters_names)"
+ " || add %(filters_names) %(buffers_plugins_names)|*"
+ " || del %(filters_names)|-all",
+ "my_command_cb", "")
+----------------------------------------
+
weechat_hook_command_run
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3919,7 +4877,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3937,6 +4895,21 @@ struct t_hook *my_command_run_hook =
&my_command_run_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_command_run(command, callback, callback_data)
+
+# example
+def my_command_run_cb(data, buffer, command):
+ weechat.prnt("", "You want to complete? I'm eating the completion, ahah!")
+ return weechat.WEECHAT_RC_OK_EAT
+
+hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")
+----------------------------------------
+
weechat_hook_timer
^^^^^^^^^^^^^^^^^^
@@ -3970,7 +4943,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -3986,6 +4959,22 @@ struct t_hook *my_timer_hook =
weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_timer(interval, align_second, max_calls, callback, callback_data)
+
+# example
+def my_timer_cb(data, remaining_calls):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+# timer called each 20 seconds
+hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")
+----------------------------------------
+
weechat_hook_fd
^^^^^^^^^^^^^^^
@@ -3999,7 +4988,8 @@ struct t_hook *weechat_hook_fd (int fd,
int flag_read,
int flag_write,
int flag_exception,
- int (*callback)(void *data, int fd),
+ int (*callback)(void *data,
+ int fd),
void *callback_data);
----------------------------------------
@@ -4019,7 +5009,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4036,6 +5026,22 @@ int sock = socket (AF_INET, SOCK_STREAM, 0);
struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_fd(fd, flag_read, flag_write, flag_exception, callback, callback_data)
+
+# example
+def my_fd_cb(data, fd):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+sock = ...
+hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")
+----------------------------------------
+
weechat_hook_process
^^^^^^^^^^^^^^^^^^^^
@@ -4077,7 +5083,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4088,10 +5094,10 @@ my_process_cb (void *data, const char *command, int return_code,
if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
{
weechat_printf (NULL, "Error with command '%s'", command);
- return;
+ return WEECHAT_RC_OK;
}
- if (return_code &gt;= 0)
+ if (return_code >= 0)
{
weechat_printf (NULL, "return_code = %d", return_code);
}
@@ -4113,6 +5119,29 @@ struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
&my_process_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_process(command, timeout, callback, callback_data)
+
+# example
+def my_process_cb(data, command, return_code, out, err):
+ if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
+ weechat.prnt("", "Error with command '%s'" % command)
+ return weechat.WEECHAT_RC_OK
+ if return_code >= 0:
+ weechat.prnt("", "return_code = %d" % return_code)
+ if out != "":
+ weechat.prnt("", "stdout: %s" % out)
+ if err != "":
+ weechat.prnt("", "stderr: %s" % err)
+ return weechat.WEECHAT_RC_OK
+
+hook = weechat.hook_process("ls", 5000, "my_process_cb", "")
+----------------------------------------
+
weechat_hook_connect
^^^^^^^^^^^^^^^^^^^^
@@ -4160,7 +5189,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4205,6 +5234,39 @@ struct t_hook *my_connect_hook = weechat_hook_connect ("my.server.org", 1234,
&my_connect_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_connect(address, port, sock, ipv6, local_hostname,
+ callback, callback_data)
+
+# example
+def my_connect_cb(data, status, ip_address):
+ if status == WEECHAT_HOOK_CONNECT_OK:
+ # ...
+ elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
+ # ...
+ elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
+ # ...
+ elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
+ # ...
+ elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR:
+ # ...
+ elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
+ # ...
+ elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
+ # ...
+ elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
+ # ...
+ elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+hook = weechat.hook_connect("my.server.org", 1234, sock, 0, "", "my_connect_cb", "")
+----------------------------------------
+
weechat_hook_print
^^^^^^^^^^^^^^^^^^
@@ -4254,7 +5316,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4273,6 +5335,22 @@ struct t_hook *my_print_hook =
weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data)
+
+# example
+def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+# catch all messages, on all buffers, without color
+hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")
+----------------------------------------
+
weechat_hook_signal
^^^^^^^^^^^^^^^^^^^
@@ -4487,7 +5565,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4504,6 +5582,22 @@ struct t_hook *my_signal_hook = weechat_hook_signal ("quit",
&my_signal_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_signal(signal, callback, callback_data)
+
+# example
+def my_signal_cb(data, signal, type_data, signal_data):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+# catch signal "quit"
+hook = weechat.hook_signal("quit", "my_signal_cb", "")
+----------------------------------------
+
weechat_hook_signal_send
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -4523,13 +5617,24 @@ Arguments:
* 'type_data': type of data sent with signal (see <<_weechat_hook_signal>>)
* 'signal_data': data sent with signal
-Example:
+C example:
[source,C]
----------------------------------------
weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.hook_signal_send(signal, type_data, signal_data)
+
+# example
+weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
+----------------------------------------
+
weechat_hook_config
^^^^^^^^^^^^^^^^^^^
@@ -4560,7 +5665,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4576,6 +5681,22 @@ struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_for
&my_config_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_config(option, callback, callback_data)
+
+# example
+def my_config_cb(data, option, value):
+ # ...
+ return weechat.WEECHAT_RC_OK
+
+# catch changes to option "weechat.look.item_time_format"
+hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")
+----------------------------------------
+
weechat_hook_completion
^^^^^^^^^^^^^^^^^^^^^^^
@@ -4615,7 +5736,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4635,6 +5756,22 @@ struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item",
&my_completion_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_completion(completion_item, callback, callback_data)
+
+# example
+def my_completion_cb(data, completion_item, buffer, completion):
+ weechat.hook_completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
+ weechat.hook_completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
+ return weechat.WEECHAT_RC_OK
+
+hook = weechat.hook_completion("plugin_item", "my_completion_cb", "")
+----------------------------------------
+
weechat_hook_completion_list_add
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -4660,7 +5797,17 @@ Arguments:
** 'WEECHAT_LIST_POS_BEGINNING': beginning of list
** 'WEECHAT_LIST_POS_END': end of list
-Example: see <<_weechat_hook_completion>>.
+C example: see <<_weechat_hook_completion>>.
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.hook_completion_list_add(completion, word, nick_completion, where)
+
+# example: see function hook_completion above
+----------------------------------------
weechat_hook_modifier
^^^^^^^^^^^^^^^^^^^^^
@@ -4759,7 +5906,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4789,6 +5936,20 @@ struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print",
&my_modifier_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_modifier(modifier, callback, callback_data)
+
+# example
+def my_modifier_cb(data, modifier, modifier_data, string):
+ return "%s xxx" % string
+
+hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")
+----------------------------------------
+
weechat_hook_modifier_exec
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -4813,7 +5974,7 @@ Return value:
* string modified, NULL if no changes in string were made by modifier(s)
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4821,6 +5982,17 @@ char *new_string = weechat_hook_modifier_exec ("my_modifier",
my_data, my_string);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.hook_modifier_exec(modifier, modifier_data, string)
+
+# example
+weechat.hook_modifier_exec("my_modifier", my_data, my_string)
+----------------------------------------
+
weechat_hook_info
^^^^^^^^^^^^^^^^^
@@ -4852,7 +6024,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4869,6 +6041,20 @@ struct t_hook *my_info_hook = weechat_hook_info ("my_info",
&my_info_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_info(info_name, description, callback, callback_data)
+
+# example
+def my_info_cb(data, info_name, arguments):
+ return "some_info"
+
+hook = weechat.hook_info("my_info", "Some info", "my_info_cb", "")
+----------------------------------------
+
weechat_hook_infolist
^^^^^^^^^^^^^^^^^^^^^
@@ -4903,7 +6089,7 @@ Return value:
* pointer to new hook, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4925,6 +6111,22 @@ struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist",
&my_infolist_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+hook = weechat.hook_infolist(infolist_name, description, callback, callback_data)
+
+# example
+def my_infolist_cb(data, infolist_name, pointer, arguments):
+ # build infolist
+ # ...
+ return my_infolist
+
+hook = weechat.hook_infolist("my_infolist", "Infolist with some data", "my_infolist_cb", "")
+----------------------------------------
+
weechat_unhook
^^^^^^^^^^^^^^
@@ -4941,7 +6143,7 @@ Arguments:
* 'hook': something hooked with "weechat_hook_xxx()"
-Example:
+C example:
[source,C]
----------------------------------------
@@ -4950,6 +6152,17 @@ struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
weechat_unhook (my_hook);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.unhook(hook)
+
+# example
+weechat.unhook(my_hook)
+----------------------------------------
+
weechat_unhook_all
^^^^^^^^^^^^^^^^^^
@@ -4962,13 +6175,24 @@ Prototype:
void weechat_unhook_all ();
----------------------------------------
-Example:
+C example:
[source,C]
----------------------------------------
weechat_unhook_all ();
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.unhook_all()
+
+# example
+weechat.unhook_all()
+----------------------------------------
+
[[buffers]]
Buffers
~~~~~~~
@@ -5012,7 +6236,7 @@ Return value:
* pointer to new buffer, NULL if error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5036,6 +6260,26 @@ struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
&my_close_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+buffer = weechat.buffer_new(name, input_callback, input_callback_data,
+ close_callback, close_callback_data)
+
+# example
+def my_input_cb(data, buffer, input_data):
+ weechat.prnt(buffer, "Text: %s" % input_data)
+ return weechat.WEECHAT_RC_OK
+
+def my_close_cb(data, buffer):
+ weechat.prnt("", "Buffer '%s' will be closed!" % weechat.buffer_get_strinf(buffer, "name"))
+ return weechat.WEECHAT_RC_OK
+
+buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
+----------------------------------------
+
weechat_current_buffer
^^^^^^^^^^^^^^^^^^^^^^
@@ -5052,13 +6296,24 @@ Return value:
* pointer to current buffer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_printf (weechat_current_buffer (), "Text on current buffer");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+buffer = weechat.current_buffer()
+
+# example
+weechat.prnt(weechat.current_buffer(), "Text on current buffer")
+----------------------------------------
+
weechat_buffer_search
^^^^^^^^^^^^^^^^^^^^^
@@ -5082,7 +6337,7 @@ Return value:
* pointer to buffer found, NULL if not found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5090,6 +6345,17 @@ struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
"my_buffer");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+buffer = weechat.buffer_search(plugin, name)
+
+# example
+buffer = weechat.buffer_search("my_plugin", "my_buffer")
+----------------------------------------
+
weechat_buffer_search_main
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5107,13 +6373,24 @@ Return value:
* pointer to WeeChat main buffer ('core' buffer)
-Example:
+C example:
[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+buffer = weechat.buffer_search_main()
+
+# example
+buffer = weechat.buffer_search_main()
+----------------------------------------
+
weechat_buffer_clear
^^^^^^^^^^^^^^^^^^^^
@@ -5130,7 +6407,7 @@ Arguments:
* 'buffer': buffer pointer
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5142,6 +6419,19 @@ if (my_buffer)
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.buffer_clear(buffer)
+
+# example
+buffer = weechat.buffer_search("my_plugin", "my_buffer")
+if buffer != "":
+ weechat.buffer_clear(buffer)
+----------------------------------------
+
weechat_buffer_close
^^^^^^^^^^^^^^^^^^^^
@@ -5158,7 +6448,7 @@ Arguments:
* 'buffer': buffer pointer
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5169,6 +6459,19 @@ struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
weechat_buffer_close (my_buffer);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.buffer_close(buffer)
+
+# example
+buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
+# ...
+weechat.buffer_close(buffer)
+----------------------------------------
+
weechat_buffer_merge
^^^^^^^^^^^^^^^^^^^^
@@ -5189,7 +6492,7 @@ Arguments:
* 'buffer': buffer pointer
* 'target_buffer': target buffer, where buffer will be merged
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5198,6 +6501,18 @@ weechat_buffer_merge (weechat_current_buffer (),
weechat_buffer_search_main ());
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.buffer_merge(buffer, target_buffer)
+
+# example
+# merge current buffer with WeeChat "core" buffer
+weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())
+----------------------------------------
+
weechat_buffer_unmerge
^^^^^^^^^^^^^^^^^^^^^^
@@ -5217,13 +6532,24 @@ Arguments:
* 'number': target number for detached buffer, if it is < 1, then buffer will
be moved to number of 'buffer' + 1
-Example:
+C example:
[source,C]
----------------------------------------
weechat_buffer_unmerge (weechat_current_buffer (), 1);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.buffer_unmerge(buffer, number)
+
+# example
+weechat.buffer_unmerge(weechat.current_buffer(), 1)
+----------------------------------------
+
weechat_buffer_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5260,7 +6586,7 @@ Return value:
* integer value of property
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5268,6 +6594,17 @@ weechat_printf (NULL, "my buffer number is: %d",
weechat_buffer_get_integer (my_buffer, "number"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.buffer_get_integer(buffer, property)
+
+# example
+weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))
+----------------------------------------
+
weechat_buffer_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5298,7 +6635,7 @@ Return value:
* string value of property
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5307,6 +6644,19 @@ weechat_printf (NULL, "name / short name of buffer are: %s / %s",
weechat_buffer_get_string (my_buffer, "short_name"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.buffer_get_string(buffer, property)
+
+# example
+weechat.prnt("", "name / short name of buffer are: %s / %s"
+ % (weechat.buffer_get_string(my_buffer, "name"),
+ weechat.buffer_get_string(my_buffer, "short_name")))
+----------------------------------------
+
weechat_buffer_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5331,7 +6681,7 @@ Return value:
* pointer value of property
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5339,6 +6689,17 @@ weechat_printf (NULL, "plugin pointer of my buffer: %lx",
weechat_buffer_get_pointer (my_buffer, "plugin"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.buffer_get_pointer(buffer, property)
+
+# example
+weechat.prnt("", "plugin pointer of my buffer: %lx" % weechat.buffer_get_pointer(my_buffer, "plugin"))
+----------------------------------------
+
weechat_buffer_set
^^^^^^^^^^^^^^^^^^
@@ -5439,7 +6800,7 @@ Arguments:
remove local variable 'xxx'
|========================================
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5459,6 +6820,31 @@ weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");
weechat_buffer_set (my_buffer, "localvar_del_toto", NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.buffer_set(buffer, property, value)
+
+# examples
+
+# disable hotlist (for all buffers)
+weechat.buffer_set("", "hotlist", "-")
+
+# enable again hotlist
+weechat.buffer_set("", "hotlist", "+")
+
+# change buffer name
+weechat.buffet_set(my_buffer, "name", "my_new_name")
+
+# add new local variable "toto" with value "abc"
+weechat.buffet_set(my_buffer, "localvar_set_toto", "abc")
+
+# remove local variable "toto"
+weechat.buffet_set(my_buffer, "localvar_del_toto", "")
+----------------------------------------
+
weechat_buffer_set_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5481,7 +6867,7 @@ Arguments:
** 'input_callback': set input callback function
** 'input_callback_data': set input callback data
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5518,7 +6904,7 @@ Return value:
* string with values of local variables
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5529,6 +6915,19 @@ char *str = weechat_buffer_string_replace_local_var (my_buffer,
/* str contains "test with abc" */
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.buffer_string_replace_local_var(buffer, string)
+
+# example
+weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
+str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto")
+# str contains "test with abc"
+----------------------------------------
+
[[windows]]
Windows
~~~~~~~
@@ -5551,13 +6950,24 @@ Return value:
* pointer to current window
-Example:
+C example:
[source,C]
----------------------------------------
struct t_gui_window *current_window = weechat_current_window ();
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+window = weechat.current_window()
+
+# example
+current_window = weechat.current_window()
+----------------------------------------
+
weechat_window_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5597,7 +7007,7 @@ Return value:
* integer value of property
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5606,6 +7016,19 @@ weechat_printf (NULL, "current window is at position (x,y): (%d,%d)",
weechat_window_get_integer (weechat_current_window (), "win_y"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.window_get_integer(window, property)
+
+# example
+weechat.prnt("", "current window is at position (x,y): (%d,%d)"
+ % (weechat.window_get_integer(weechat.current_window(), "win_x"),
+ weechat.window_get_integer(weechat.current_window(), "win_y")))
+----------------------------------------
+
weechat_window_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5655,7 +7078,7 @@ Return value:
* pointer value of property
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5664,6 +7087,52 @@ weechat_printf (NULL,
weechat_window_get_pointer (weechat_current_window (), "buffer"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.window_get_pointer(window, property)
+
+# example
+weechat.prnt("", "buffer displayed in current window: %lx"
+ % weechat.window_get_pointer(weechat.current_window(), "buffer"))
+----------------------------------------
+
+weechat_window_set_title
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set title for terminal.
+
+Prototype:
+
+[source,C]
+----------------------------------------
+void weechat_window_set_title (const char *title);
+----------------------------------------
+
+Arguments:
+
+* 'title': new title for terminal (NULL to reset title)
+
+C example:
+
+[source,C]
+----------------------------------------
+weechat_window_set_title ("new title here");
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.window_set_title(window, title)
+
+# example
+weechat.window_set_title("new title here")
+----------------------------------------
+
[[nicklist]]
Nicklist
~~~~~~~~
@@ -5713,7 +7182,7 @@ Return value:
* pointer to new group, NULL if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5725,6 +7194,18 @@ struct t_gui_nick_group *my_group =
1);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+group = weechat.nicklist_add_group(buffer, parent_group, name, color, visible)
+
+# example
+group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group",
+ "weechat.color.nicklist_group", 1)
+----------------------------------------
+
weechat_nicklist_search_group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5750,7 +7231,7 @@ Return value:
* pointer to group found, NULL if not found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5758,6 +7239,17 @@ struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer,
NULL, "test_group");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+group = weechat.nicklist_search_group(buffer, from_group, name)
+
+# example
+group = weechat.nicklist_search_group(my_buffer, "", "test_group")
+----------------------------------------
+
weechat_nicklist_add_nick
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5804,7 +7296,7 @@ Return value:
* pointer to new nick, NULL if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5816,6 +7308,21 @@ struct t_gui_nick *my_nick =
1);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+nick = weechat.nicklist_add_nick(buffer, group, name, color, prefix, prefix_color, visible)
+
+# example
+if nick_away:
+ color = "weechat.color.nicklist_away"
+else:
+ color = "bar_fg"
+nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)
+----------------------------------------
+
weechat_nicklist_search_nick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5841,7 +7348,7 @@ Return value:
* pointer to nick found, NULL if not found
-Example:
+C example:
[source,C]
----------------------------------------
@@ -5849,6 +7356,17 @@ struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer,
NULL, "test_nick");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+nick = weechat.nicklist_search_nick(buffer, from_group, name)
+
+# example
+nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
+----------------------------------------
+
weechat_nicklist_remove_group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5867,13 +7385,24 @@ Arguments:
* 'buffer': buffer pointer
* 'group': group pointer to remove (all sub-groups/nicks will be removed too)
-Example:
+C example:
[source,C]
----------------------------------------
weechat_nicklist_remove_group (my_buffer, my_group);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.nicklist_remove_group(buffer, group)
+
+# example
+weechat.nicklist_remove_group(my_buffer, my_group)
+----------------------------------------
+
weechat_nicklist_remove_nick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5892,13 +7421,24 @@ Arguments:
* 'buffer': buffer pointer
* 'nick': nick pointer to remove
-Example:
+C example:
[source,C]
----------------------------------------
weechat_nicklist_remove_nick (my_buffer, my_nick);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.nicklist_remove_nick(buffer, nick)
+
+# example
+weechat.nicklist_remove_nick(my_buffer, my_nick)
+----------------------------------------
+
weechat_nicklist_remove_all
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -5915,13 +7455,24 @@ Arguments:
* 'buffer': buffer pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_nicklist_remove_all (my_buffer);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.nicklist_remove_all(buffer)
+
+# example
+weechat.nicklist_remove_all(my_buffer)
+----------------------------------------
+
[[bars]]
Bars
~~~~
@@ -5948,13 +7499,24 @@ Return value:
* pointer to bar item found, NULL if bar item was not found
-Example:
+C example:
[source,C]
----------------------------------------
struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+bar_item = weechat.bar_item_search(name)
+
+# example
+bar_item = weechat.bar_item_search("myitem")
+----------------------------------------
+
weechat_bar_item_new
^^^^^^^^^^^^^^^^^^^^
@@ -5983,7 +7545,7 @@ Return value:
* pointer to new bar item, NULL if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6000,6 +7562,20 @@ struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+bar_item = weechat.bar_item_new(name, build_callback, build_callback_data)
+
+# example
+def my_build_callback(data, item, window):
+ return "my content"
+
+bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")
+----------------------------------------
+
weechat_bar_item_update
^^^^^^^^^^^^^^^^^^^^^^^
@@ -6016,13 +7592,24 @@ Arguments:
* 'name': bar item name
-Example:
+C example:
[source,C]
----------------------------------------
weechat_bar_item_update ("myitem");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.bar_item_update(name)
+
+# example
+weechat.bar_item_update("myitem")
+----------------------------------------
+
weechat_bar_item_remove
^^^^^^^^^^^^^^^^^^^^^^^
@@ -6039,13 +7626,24 @@ Arguments:
* 'item': bar item pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_bar_item_remove (&my_item);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.bar_item_remove(item)
+
+# example
+weechat.bar_item_remove(myitem)
+----------------------------------------
+
weechat_bar_search
^^^^^^^^^^^^^^^^^^
@@ -6066,13 +7664,24 @@ Return value:
* pointer to bar found, NULL if bar was not found
-Example:
+C example:
[source,C]
----------------------------------------
struct t_gui_bar *bar = weechat_bar_search ("mybar");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+bar = weechat.bar_search(name)
+
+# example
+bar = weechat.bar_search("mybar")
+----------------------------------------
+
weechat_bar_new
^^^^^^^^^^^^^^^
@@ -6139,7 +7748,7 @@ Return value:
* pointer to new bar, NULL if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6160,6 +7769,20 @@ struct t_gui_bar *my_bar = weechat_bar_new ("mybar",
"time,buffer_number+buffer_name");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+bar = weechat.bar_new(name, hidden, priority, type, condition, position,
+ filling_top_bottom, filling_left_right, size, size_max,
+ color_fg, color_delim, color_bg, separator, items)
+
+# example
+bar = weechat.bar_new("mybar", "off", 100, "window", "", "top", "horizontal", "vertical",
+ "0", "5", "default", "cyan", "blue", "off", "time,buffer_number+buffer_name")
+----------------------------------------
+
weechat_bar_set
^^^^^^^^^^^^^^^
@@ -6185,13 +7808,24 @@ Return value:
* 1 if new value was set, 0 if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
weechat_bar_set (mybar, "position", "bottom");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.bar_set(bar, property, value)
+
+# example
+weechat.bar_set(my_bar, "position", "bottom")
+----------------------------------------
+
weechat_bar_update
^^^^^^^^^^^^^^^^^^
@@ -6208,13 +7842,24 @@ Arguments:
* 'name': bar name
-Example:
+C example:
[source,C]
----------------------------------------
weechat_bar_update ("mybar");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.bar_update(name)
+
+# example
+weechat.bar_update("mybar")
+----------------------------------------
+
weechat_bar_remove
^^^^^^^^^^^^^^^^^^
@@ -6231,13 +7876,24 @@ Arguments:
* 'bar': bar pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_bar_remove (mybar);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.bar_remove(bar)
+
+# example
+weechat.bar_remove(my_bar)
+----------------------------------------
+
[[commands]]
Commands
~~~~~~~~
@@ -6263,7 +7919,7 @@ Arguments:
* 'command': command to execute (if beginning with a "/"), or text to send to
buffer
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6271,6 +7927,17 @@ weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"),
"/whois FlashCode");
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.command(buffer, command)
+
+# example
+weechat.command(weechat.buffer_search("irc", "freenode.#weechat"), "/whois FlashCode")
+----------------------------------------
+
[[network]]
Network
~~~~~~~
@@ -6303,7 +7970,7 @@ Return value:
* 1 if connection is ok, 0 if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6343,7 +8010,7 @@ Return value:
* 1 if connection is ok, 0 if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6396,7 +8063,7 @@ Return value:
* string with info asked, NULL if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6407,6 +8074,19 @@ weechat_printf (NULL, "WeeChat home is: %s",
weechat_info_get ("weechat_dir"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.info_get(info_name, arguments)
+
+# example
+weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)"
+ % (weechat.info_get("version", ""), weechat.info_get("date", ""))
+weechat.prnt("", "WeeChat home is: %s" % weechat.info_get("weechat_dir"))
+----------------------------------------
+
[[infolists]]
Infolists
~~~~~~~~~
@@ -6441,13 +8121,24 @@ Return value:
* pointer to new infolist
-Example:
+C example:
[source,C]
----------------------------------------
struct t_infolist *infolist = weechat_infolist_new ();
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+infolist = weechat.infolist_new()
+
+# example
+infolist = weechat.infolist_new()
+----------------------------------------
+
weechat_infolist_new_item
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -6468,13 +8159,24 @@ Return value:
* pointer to new item
-Example:
+C example:
[source,C]
----------------------------------------
struct t_infolist_item *item = weechat_infolist_new_item (infolist);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+item = weechat.infolist_new_item(infolist)
+
+# example
+item = weechat.infolist_new_item(infolist)
+----------------------------------------
+
weechat_infolist_new_var_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -6499,13 +8201,24 @@ Return value:
* pointer to new variable
-Example:
+C example:
[source,C]
----------------------------------------
-struct t_infolist_var *var = weechat_infolist_new_variable_integer (item,
- "my_integer",
- 123);
+struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
+ "my_integer",
+ 123);
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+var = weechat.infolist_new_var_integer(item, name, value)
+
+# example
+var = weechat.infolist_new_var_integer(item, "my_integer", 123)
----------------------------------------
weechat_infolist_new_var_string
@@ -6532,13 +8245,24 @@ Return value:
* pointer to new variable
-Example:
+C example:
[source,C]
----------------------------------------
-struct t_infolist_var *var = weechat_infolist_new_variable_integer (item,
- "my_string",
- "value");
+struct t_infolist_var *var = weechat_infolist_new_var_string (item,
+ "my_string",
+ "value");
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+var = weechat.infolist_new_var_string(item, name, value)
+
+# example
+var = weechat.infolist_new_var_string(item, "my_string", "value")
----------------------------------------
weechat_infolist_new_var_pointer
@@ -6565,13 +8289,24 @@ Return value:
* pointer to new variable
-Example:
+C example:
[source,C]
----------------------------------------
-struct t_infolist_var *var = weechat_infolist_new_variable_pointer (item,
- "my_pointer",
- &something);
+struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
+ "my_pointer",
+ &pointer);
+----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+var = weechat.infolist_new_var_pointer(item, name, pointer)
+
+# example
+var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)
----------------------------------------
weechat_infolist_new_var_buffer
@@ -6600,7 +8335,7 @@ Return value:
* pointer to new variable
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6636,7 +8371,7 @@ Return value:
* pointer to new variable
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6645,6 +8380,17 @@ struct t_infolist_var *var = weechat_infolist_new_variable_time (item,
time (NULL));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+var = weechat.infolist_new_var_time(item, name, time)
+
+# example
+var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))
+----------------------------------------
+
weechat_infolist_get
^^^^^^^^^^^^^^^^^^^^
@@ -6672,13 +8418,24 @@ Return value:
* pointer to infolist, NULL if an error occured
-Example:
+C example:
[source,C]
----------------------------------------
struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+infolist = weechat.infolist_get(infolist_name, pointer, arguments)
+
+# example
+infolist = weechat.infolist_get("irc_server, "", "")
+----------------------------------------
+
weechat_infolist_next
^^^^^^^^^^^^^^^^^^^^^
@@ -6700,7 +8457,7 @@ Return value:
* 1 if cursor has been moved on next item, 0 if end of list was reached
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6714,6 +8471,21 @@ else
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.infolist_next(infolist)
+
+# example
+rc = weechat.infolist_next(infolist)
+if rc:
+ # read variables in item...
+else:
+ # no more item available
+----------------------------------------
+
weechat_infolist_prev
^^^^^^^^^^^^^^^^^^^^^
@@ -6736,7 +8508,7 @@ Return value:
* 1 if cursor has been moved on previous item, 0 if beginning of list was
reached
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6750,6 +8522,21 @@ else
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+rc = weechat.infolist_prev(infolist)
+
+# example
+rc = weechat.infolist_prev(infolist)
+if rc:
+ # read variables in item...
+else:
+ # no more item available
+----------------------------------------
+
weechat_infolist_reset_item_cursor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -6766,13 +8553,24 @@ Arguments:
* 'infolist': infolist pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_infolist_reset_item_cursor (infolist);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.infolist_reset_item_cursor(infolist)
+
+# example
+weechat.infolist_reset_item_cursor(infolist)
+----------------------------------------
+
weechat_infolist_fields
^^^^^^^^^^^^^^^^^^^^^^^
@@ -6795,7 +8593,7 @@ Return value:
separated, and contains letter for type, followed by variable name. Types
are: "i" (integer), "s" (string), "p" (pointer), "b" (buffer), "t" (time).
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6804,6 +8602,19 @@ const char *fields = weechat_infolist_fields (infolist);
"i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+fields = weechat.infolist_fields(infolist)
+
+# example
+fields = weechat.infolist_fields(infolist)
+# fields contains something like:
+# "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time"
+----------------------------------------
+
weechat_infolist_integer
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -6825,7 +8636,7 @@ Return value:
* integer value of variable
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6833,6 +8644,17 @@ weechat_printf (NULL, "integer = %d",
weechat_infolist_integer (infolist, "my_integer"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.infolist_integer(infolist, var)
+
+# example
+weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer"))
+----------------------------------------
+
weechat_infolist_string
^^^^^^^^^^^^^^^^^^^^^^^
@@ -6854,7 +8676,7 @@ Return value:
* string value of variable
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6862,6 +8684,17 @@ weechat_printf (NULL, "string = %s",
weechat_infolist_string (infolist, "my_string"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.infolist_string(infolist, var)
+
+# example
+weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string"))
+----------------------------------------
+
weechat_infolist_pointer
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -6883,7 +8716,7 @@ Return value:
* pointer value of variable
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6891,6 +8724,17 @@ weechat_printf (NULL, "pointer = 0x%lx",
weechat_infolist_pointer (infolist, "my_pointer"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.infolist_pointer(infolist, var)
+
+# example
+weechat.prnt("", "pointer = 0x%lx" % weechat.infolist_pointer(infolist, "my_pointer"))
+----------------------------------------
+
weechat_infolist_buffer
^^^^^^^^^^^^^^^^^^^^^^^
@@ -6914,7 +8758,7 @@ Return value:
* buffer pointer
-Example:
+C example:
[source,C]
----------------------------------------
@@ -6945,14 +8789,25 @@ Return value:
* time value of variable
-Example:
+C example:
[source,C]
----------------------------------------
-weechat_printf (NULL, "time = 0x%ld",
+weechat_printf (NULL, "time = %ld",
weechat_infolist_time (infolist, "my_time"));
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+value = weechat.infolist_time(infolist, var)
+
+# example
+weechat.prnt("", "time = %ld" % weechat.infolist_time(infolist, "my_time"))
+----------------------------------------
+
weechat_infolist_free
^^^^^^^^^^^^^^^^^^^^^
@@ -6969,13 +8824,24 @@ Arguments:
* 'infolist': infolist pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_infolist_free (infolist);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.infolist_free(infolist)
+
+# example
+weechat.infolist_free(infolist)
+----------------------------------------
+
[[upgrade]]
Upgrade
~~~~~~~
@@ -7006,13 +8872,24 @@ Return value:
* pointer to upgrade file
-Example:
+C example:
[source,C]
----------------------------------------
struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file", 1);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+upgrade_file = weechat.upgrade_new(filename, write)
+
+# example
+upgrade_file = weechat.upgrade_new("my_file", 1)
+----------------------------------------
+
weechat_upgrade_write_object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -7037,7 +8914,7 @@ Return value:
* 1 if ok, 0 if error
-Example:
+C example:
[source,C]
----------------------------------------
@@ -7051,6 +8928,17 @@ else
}
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.upgrade_write_object(upgrade_file, object_id, infolist)
+
+# example
+weechat.upgrade_write_object(upgrade_file, 1, infolist)
+----------------------------------------
+
weechat_upgrade_read
^^^^^^^^^^^^^^^^^^^^
@@ -7079,7 +8967,7 @@ Return value:
* 1 if ok, 0 if error
-Example:
+C example:
[source,C]
----------------------------------------
@@ -7095,6 +8983,21 @@ my_upgrade_read_cb (struct t_upgrade_file *upgrade_file,
weechat_upgrade_read (upgrade_file, &my_upgrade_read_cb, NULL);
----------------------------------------
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.upgrade_read(upgrade_file, callback_read, callback_read_data)
+
+# example
+def my_upgrade_read_cb(upgrade_file, object_id, infolist):
+ # read variables...
+ return weechat.WEECHAT_RC_OK
+
+weechat.upgrade_read(upgrade_file, "my_upgrade_read_cb", ""))
+----------------------------------------
+
weechat_upgrade_close
^^^^^^^^^^^^^^^^^^^^^
@@ -7111,9 +9014,20 @@ Arguments:
* 'upgrade_file': upgrade file pointer
-Example:
+C example:
[source,C]
----------------------------------------
weechat_upgrade_close (upgrade_file);
----------------------------------------
+
+Script (Python):
+
+[source,python]
+----------------------------------------
+# prototype
+weechat.upgrade_close(upgrade_file)
+
+# example
+weechat.upgrade_close(upgrade_file)
+----------------------------------------
diff --git a/doc/en/weechat_scripting.en.txt b/doc/en/weechat_scripting.en.txt
index 07d5c0b59..759e8ba3c 100644
--- a/doc/en/weechat_scripting.en.txt
+++ b/doc/en/weechat_scripting.en.txt
@@ -146,9 +146,9 @@ $ cd ~/.weechat/perl/autoload
$ ln -s ../script.pl
----------------------------------------
-[[script_api]]
-Script API
-----------
+[[differences_with_c_api]]
+Differences with C API
+----------------------
Script API is almost the same as C plugin API.
You can look at 'WeeChat Plugin API Reference' for detail about each function
@@ -176,6 +176,60 @@ previous path:
WeeChat core -------> python plugin (python.so) -------> test.py
........................................
+Pointers
+~~~~~~~~
+
+As you probably know, there is not really "pointers" in scripts. So when API
+functions return pointer, it is converted to string for script.
+
+For example, if function return pointer 0x1234ab56, script will get string
+"0x1234ab56".
+
+And when an API function expects a pointer in arguments, script must give that
+string value. C plugin will convert it to real pointer before calling C API
+function.
+
+Empty string or "0x0" are allowed, they means NULL in C.
+For example, to print data on core buffer (WeeChat main buffer), you can do:
+
+[source,python]
+----------------------------------------
+weechat.prnt("", "hi!")
+----------------------------------------
+
+[WARNING]
+In many functions, for speed reasons, WeeChat does not check if your pointer
+is correct or not. It's your job to check you're giving a valid pointer,
+otherwise you may see a nice crash report ;)
+
+Callbacks
+~~~~~~~~~
+
+Almost all WeeChat callbacks must return WEECHAT_RC_OK or WEECHAT_RC_ERROR
+(exception is modifier callback, which returns a string).
+
+C callbacks are using a "data" argument, which is a pointer. In script API,
+this "data" is a string with a any value (it's not a pointer).
+
+For example:
+
+[source,python]
+----------------------------------------
+weechat.hook_timer(1000, 0, 1, "my_timer_cb", "my data")
+
+def my_timer_cb(data, remaining_calls):
+ # this will display: "my data"
+ weechat.prnt("", data)
+ return weechat.WEECHAT_RC_OK
+----------------------------------------
+
+[[script_api]]
+Script API
+----------
+
+For more information about functions in API, please read
+'WeeChat Plugin API Reference'.
+
Functions
~~~~~~~~~
@@ -274,18 +328,21 @@ List of functions in script API:
** 'unhook_all'
* buffers:
** 'buffer_new'
-** 'buffer_search'
** 'current_buffer'
+** 'buffer_search'
+** 'buffer_search_main'
** 'buffer_clear'
** 'buffer_close'
+** 'buffer_merge'
+** 'buffer_unmerge'
** 'buffer_get_integer'
** 'buffer_get_string'
** 'buffer_get_pointer'
** 'buffer_set'
+** 'buffer_string_replace_local_var'
* windows:
** 'current_window'
** 'window_get_integer'
-** 'window_get_string'
** 'window_get_pointer'
** 'window_set_title'
* nicklist:
@@ -312,6 +369,7 @@ List of functions in script API:
** 'info_get'
* infolists:
** 'infolist_new'
+** 'infolist_new_item'
** 'infolist_new_var_integer'
** 'infolist_new_var_string'
** 'infolist_new_var_pointer'
@@ -319,6 +377,7 @@ List of functions in script API:
** 'infolist_get'
** 'infolist_next'
** 'infolist_prev'
+** 'infolist_reset_item_cursor'
** 'infolist_fields'
** 'infolist_integer'
** 'infolist_string'
@@ -374,53 +433,3 @@ List of constants in script API:
* 'WEECHAT_HOOK_SIGNAL_STRING'
* 'WEECHAT_HOOK_SIGNAL_INT'
* 'WEECHAT_HOOK_SIGNAL_POINTER'
-
-Differences with C API
-~~~~~~~~~~~~~~~~~~~~~~
-
-Pointers
-^^^^^^^^
-
-As you probably know, there is not really "pointers" in scripts. So when API
-functions return pointer, it is converted to string for script.
-
-For example, if function return pointer 0x1234ab56, script will get string
-"0x1234ab56".
-
-And when an API function expects a pointer in arguments, script must give that
-string value. C plugin will convert it to real pointer before calling C API
-function.
-
-Empty string or "0x0" are allowed, they means NULL in C.
-For example, to print data on core buffer (WeeChat main buffer), you can do:
-
-[source,python]
-----------------------------------------
-weechat.prnt("", "hi!")
-----------------------------------------
-
-[WARNING]
-In many functions, for speed reasons, WeeChat does not check if your pointer
-is correct or not. It's your job to check you're giving a valid pointer,
-otherwise you may see a nice crash report ;)
-
-Callbacks
-^^^^^^^^^
-
-Almost all WeeChat callbacks must return WEECHAT_RC_OK or WEECHAT_RC_ERROR
-(exception is modifier callback, which returns a string).
-
-C callbacks are using a "data" argument, which is a pointer. In script API,
-this "data" is a string with a any value (it's not a pointer).
-
-For example:
-
-[source,python]
-----------------------------------------
-weechat.hook_timer(1000, 0, 1, "my_timer_cb", "my data")
-
-def my_timer_cb(data, remaining_calls):
- # this will display: "my data"
- weechat.prnt("", data)
- return weechat.WEECHAT_RC_OK
-----------------------------------------