diff --git a/doc/en/weechat_plugin_api.en.txt b/doc/en/weechat_plugin_api.en.txt index 6d728032c..0c594a14b 100644 --- a/doc/en/weechat_plugin_api.en.txt +++ b/doc/en/weechat_plugin_api.en.txt @@ -866,7 +866,7 @@ Arguments: Return value: * array of strings, NULL if problem (must be freed by calling - <<_weechat_string_free_split>> after use) + <<_weechat_string_free_split,weechat_string_free_split>> after use) C examples: @@ -907,7 +907,8 @@ void weechat_string_free_split (char **split_string); Arguments: -* 'split_string': string split by function <<_weechat_string_split>> +* 'split_string': string split by function + <<_weechat_string_split,weechat_string_split>> C example: @@ -935,7 +936,8 @@ char *weechat_string_build_with_split_string (char **split_string, Arguments: -* 'split_string': string split by function <<_weechat_string_split>> +* 'split_string': string split by function + <<_weechat_string_split,weechat_string_split>> * 'separator': string used to separate strings Return value: @@ -976,7 +978,7 @@ Arguments: Return value: * array of strings, NULL if problem (must be freed by calling - <<_weechat_free_split_command>> after use) + <<_weechat_free_split_command,weechat_free_split_command>> after use) C example: @@ -1003,7 +1005,8 @@ void weechat_string_free_split_command (char **split_command); Arguments: -* 'split_command': command split by <<_weechat_string_split_command>> +* 'split_command': command split by + <<_weechat_string_split_command,weechat_string_split_command>> C example: @@ -2507,9 +2510,10 @@ Return value: [NOTE] File is NOT created on disk by this function. It will be created by call to -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>>). +function <<_weechat_write_config,weechat_write_config>>. +You should call this function only after adding some sections (with +<<_weechat_config_new_section,weechat_config_new_section>>) and options (with +<<_weechat_config_new_option,weechat_config_new_option>>). C example: @@ -3282,7 +3286,7 @@ Arguments: [NOTE] You can set value to null only if it is allowed for option (see -<<_weechat_config_new_option>>). +<<_weechat_config_new_option,weechat_config_new_option>>). Return value: @@ -4999,9 +5003,7 @@ 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]", + "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]", "description of arguments...", "list" " || enable %(filters_names)" @@ -5805,7 +5807,8 @@ void weechat_hook_signal_send (const char *signal, const char *type_data, Arguments: * 'signal': signal to send -* 'type_data': type of data sent with signal (see <<_weechat_hook_signal>>) +* 'type_data': type of data sent with signal (see + <<_weechat_hook_signal,weechat_hook_signal>>) * 'signal_data': data sent with signal C example: @@ -5917,7 +5920,8 @@ Arguments: ** 'const char *completion_item': name of completion item ** 'struct t_gui_buffer *buffer': buffer where completion is made ** 'struct t_gui_completion *completion': structure used to add words for - completion (see <<_weechat_hook_completion_list_add>>) + completion (see + <<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>>) * 'callback_data': pointer given to callback when it is called by WeeChat [NOTE] @@ -5992,7 +5996,7 @@ Arguments: ** 'WEECHAT_LIST_POS_BEGINNING': beginning of list ** 'WEECHAT_LIST_POS_END': end of list -C example: see <<_weechat_hook_completion>>. +C example: see <<_weechat_hook_completion,weechat_hook_completion>>. Script (Python): @@ -8032,7 +8036,7 @@ Arguments: * 'bar': bar pointer * 'property': name, hidden, priority, conditions, position, filling_top_bottom, filling_left_right, size, size_max, color_fg, color_delim, color_bg, - separator, items (see <<_weechat_bar_new>>) + separator, items (see <<_weechat_bar_new,weechat_bar_new>>) * 'value': new value for property Return value: diff --git a/doc/en/weechat_scripting.en.txt b/doc/en/weechat_scripting.en.txt index 759e8ba3c..cc223f618 100644 --- a/doc/en/weechat_scripting.en.txt +++ b/doc/en/weechat_scripting.en.txt @@ -46,9 +46,9 @@ Some things are specific to languages: * tcl: ** functions are called with `weechat::xxx arg1 arg2 ...` -[[register]] -Register -~~~~~~~~ +[[register_function]] +Register function +~~~~~~~~~~~~~~~~~ All WeeChat scripts must "register" themselves to WeeChat, and this must be first WeeChat function called in script. @@ -71,10 +71,6 @@ Arguments: * 'charset': string, script charset (optional, if your script is UTF-8, you can use blank value here, because UTF-8 is default charset) -[[script_example]] -Script example -~~~~~~~~~~~~~~ - Example of script, for each language: * perl: @@ -139,11 +135,11 @@ You have to use command, depending on language: You can make link in directory 'language/autoload' to autoload script when WeeChat is starting. -For example with perl: +For example with Python: ---------------------------------------- -$ cd ~/.weechat/perl/autoload -$ ln -s ../script.pl +$ cd ~/.weechat/python/autoload +$ ln -s ../script.py ---------------------------------------- [[differences_with_c_api]] @@ -156,8 +152,8 @@ in API: prototype, arguments, return values, examples. It's important to make difference between a 'plugin' and a 'script': a 'plugin' is a binary file compiled and loaded with command `/plugin`, whereas -a 'script' is a text file loaded with a plugin like 'perl' with command -`/perl`. +a 'script' is a text file loaded with a plugin like 'python' with command +`/python`. When your script 'test.py' calls a WeeChat API function, path is like that: @@ -176,6 +172,7 @@ previous path: WeeChat core -------> python plugin (python.so) -------> test.py ........................................ +[[pointers]] Pointers ~~~~~~~~ @@ -202,6 +199,7 @@ 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]] Callbacks ~~~~~~~~~ @@ -230,206 +228,527 @@ Script API For more information about functions in API, please read 'WeeChat Plugin API Reference'. +[[script_api_functions]] Functions ~~~~~~~~~ List of functions in script API: -* general: -** 'register' -* plugins: -** 'plugin_get_name' -* strings: -** 'charset_set' -** 'iconv_to_internal' -** 'iconv_from_internal' -** 'gettext' -** 'ngettext' -** 'string_remove_color' -* directories: -** 'mkdir_home' -** 'mkdir' -** 'mkdir_parents' -* sorted lists: -** 'list_new' -** 'list_add' -** 'list_search' -** 'list_casesearch' -** 'list_get' -** 'list_set' -** 'list_next' -** 'list_prev' -** 'list_string' -** 'list_size' -** 'list_remove' -** 'list_remove_all' -** 'list_free' -* configuration files: -** 'config_new' -** 'config_new_section' -** 'config_search_section' -** 'config_new_option' -** 'config_search_option' -** 'config_string_to_boolean' -** 'config_option_reset' -** 'config_option_set' -** 'config_option_set_null' -** 'config_option_unset' -** 'config_option_rename' -** 'config_option_is_null' -** 'config_option_default_is_null' -** 'config_boolean' -** 'config_boolean_default' -** 'config_integer' -** 'config_integer_default' -** 'config_string' -** 'config_string_default' -** 'config_color' -** 'config_color_default' -** 'config_write_option' -** 'config_write_line' -** 'config_write' -** 'config_read' -** 'config_reload' -** 'config_option_free' -** 'config_section_free_options' -** 'config_section_free' -** 'config_free' -** 'config_get' -** 'config_get_plugin' -** 'config_is_set_plugin' -** 'config_set_plugin' -** 'config_unset_plugin' -* display: -** 'prefix' -** 'color' -** 'print' (for python: 'prnt') -** 'print_date_tags' (for python: 'prnt_date_tags') -** 'print_y' (for python: 'prnt_y') -** 'log_print' -* hooks: -** 'hook_command' -** 'hook_command_run' -** 'hook_timer' -** 'hook_fd' -** 'hook_process' -** 'hook_connect' -** 'hook_print' -** 'hook_signal' -** 'hook_signal_send' -** 'hook_config' -** 'hook_completion' -** 'hook_completion_list_add' -** 'hook_modifier' -** 'hook_modifier_exec' -** 'hook_info' -** 'hook_infolist' -** 'unhook' -** 'unhook_all' -* buffers: -** 'buffer_new' -** '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_pointer' -** 'window_set_title' -* nicklist: -** 'nicklist_add_group' -** 'nicklist_search_group' -** 'nicklist_add_nick' -** 'nicklist_search_nick' -** 'nicklist_remove_group' -** 'nicklist_remove_nick' -** 'nicklist_remove_all' -* bars: -** 'bar_item_search' -** 'bar_item_new' -** 'bar_item_update' -** 'bar_item_remove' -** 'bar_search' -** 'bar_new' -** 'bar_set' -** 'bar_update' -** 'bar_remove' -* commands: -** 'command' -* infos: -** 'info_get' -* infolists: -** 'infolist_new' -** 'infolist_new_item' -** 'infolist_new_var_integer' -** 'infolist_new_var_string' -** 'infolist_new_var_pointer' -** 'infolist_new_var_time' -** 'infolist_get' -** 'infolist_next' -** 'infolist_prev' -** 'infolist_reset_item_cursor' -** 'infolist_fields' -** 'infolist_integer' -** 'infolist_string' -** 'infolist_pointer' -** 'infolist_time' -** 'infolist_free' -* upgrade: -** 'upgrade_new' -** 'upgrade_write_object' -** 'upgrade_read' -** 'upgrade_close' +[width="100%",cols="^1,10",options="header"] +|======================================== +| Category | Functions +| general | + register +| plugins | + plugin_get_name +| strings | + charset_set, iconv_to_internal, iconv_from_internal, + + gettext, ngettext, + string_remove_color, + + string_is_command_char, string_input_for_buffer +| directories | + mkdir_home, mkdir, mkdir_parents +| sorted lists | + list_new, list_add, list_search, list_casesearch, list_get, list_set, + list_next, list_prev, list_string, list_size, list_remove, list_remove_all, + list_free +| configuration files | + config_new, config_new_section, config_search_section, config_new_option, + config_search_option, + + config_string_to_boolean, config_option_reset, config_option_set, + config_option_set_null, config_option_unset, config_option_rename, + config_option_is_null, config_option_default_is_null, + + config_boolean, config_boolean_default, config_integer, config_integer_default, + config_string, config_string_default, config_color, config_color_default, + + config_write_option, config_write_line, config_write, config_read, + config_reload, + + config_option_free, config_section_free_options, config_section_free, + config_free, + + config_get, config_get_plugin, config_is_set_plugin, config_set_plugin, + config_unset_plugin +| display | + prefix, color, print (for python: prnt), print_date_tags (for python: + prnt_date_tags), print_y (for python: prnt_y), log_print +| hooks | + hook_command, hook_command_run, hook_timer, hook_fd, hook_process, + hook_connect, hook_print, hook_signal, hook_signal_send, hook_config, + hook_completion, hook_completion_list_add, hook_modifier, hook_modifier_exec, + hook_info, hook_infolist, unhook, unhook_all +| buffers | + buffer_new, 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 | + nicklist_add_group, nicklist_search_group, nicklist_add_nick, + nicklist_search_nick, nicklist_remove_group, nicklist_remove_nick, + nicklist_remove_all +| bars | + bar_item_search, bar_item_new, bar_item_update, bar_item_remove, bar_search, + bar_new, bar_set, bar_update, bar_remove +| commands | + command +| infos | + info_get +| infolists | + infolist_new, infolist_new_item, infolist_new_var_integer, + infolist_new_var_string, infolist_new_var_pointer, infolist_new_var_time, + + infolist_get, infolist_next, infolist_prev, infolist_fields, infolist_integer, + infolist_string, infolist_pointer, infolist_time, infolist_free +| upgrade | + upgrade_new, upgrade_write_object, upgrade_read, upgrade_close +|======================================== +[[script_api_constants]] Constants ~~~~~~~~~ List of constants in script API: -* 'WEECHAT_RC_OK' -* 'WEECHAT_RC_OK_EAT' -* 'WEECHAT_RC_ERROR' -* 'WEECHAT_CONFIG_READ_OK' -* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' -* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' -* 'WEECHAT_CONFIG_WRITE_OK' -* 'WEECHAT_CONFIG_WRITE_ERROR' -* 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR' -* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' -* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' -* 'WEECHAT_CONFIG_OPTION_SET_ERROR' -* 'WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND' -* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' -* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' -* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' -* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' -* 'WEECHAT_LIST_POS_SORT' -* 'WEECHAT_LIST_POS_BEGINNING' -* 'WEECHAT_LIST_POS_END' -* 'WEECHAT_HOTLIST_LOW' -* 'WEECHAT_HOTLIST_MESSAGE' -* 'WEECHAT_HOTLIST_PRIVATE' -* 'WEECHAT_HOTLIST_HIGHLIGHT' -* 'WEECHAT_HOOK_PROCESS_RUNNING' -* 'WEECHAT_HOOK_PROCESS_ERROR' -* 'WEECHAT_HOOK_CONNECT_OK' -* 'WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND' -* 'WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND' -* 'WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED' -* 'WEECHAT_HOOK_CONNECT_PROXY_ERROR' -* 'WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR' -* 'WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR' -* 'WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR' -* 'WEECHAT_HOOK_CONNECT_MEMORY_ERROR' -* 'WEECHAT_HOOK_SIGNAL_STRING' -* 'WEECHAT_HOOK_SIGNAL_INT' -* 'WEECHAT_HOOK_SIGNAL_POINTER' +[width="100%",cols="^1,10",options="header"] +|======================================== +| Category | Constants +| return codes | + WEECHAT_RC_OK, WEECHAT_RC_OK_EAT, WEECHAT_RC_ERROR +| configuration files | + WEECHAT_CONFIG_READ_OK, WEECHAT_CONFIG_READ_MEMORY_ERROR, + WEECHAT_CONFIG_READ_FILE_NOT_FOUND, WEECHAT_CONFIG_WRITE_OK, + WEECHAT_CONFIG_WRITE_ERROR, WEECHAT_CONFIG_WRITE_MEMORY_ERROR, + + WEECHAT_CONFIG_OPTION_SET_OK_CHANGED, WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE, + WEECHAT_CONFIG_OPTION_SET_ERROR, WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND, + WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET, WEECHAT_CONFIG_OPTION_UNSET_OK_RESET, + WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED, WEECHAT_CONFIG_OPTION_UNSET_ERROR +| sorted lists | + WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING, WEECHAT_LIST_POS_END +| hotlist | + WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, + WEECHAT_HOTLIST_HIGHLIGHT +| hook process | + WEECHAT_HOOK_PROCESS_RUNNING, WEECHAT_HOOK_PROCESS_ERROR +| hook connect | + WEECHAT_HOOK_CONNECT_OK, WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND, + WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND, WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED, + WEECHAT_HOOK_CONNECT_PROXY_ERROR, WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR, + WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR, WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR, + WEECHAT_HOOK_CONNECT_MEMORY_ERROR +| hook signal | + WEECHAT_HOOK_SIGNAL_STRING, WEECHAT_HOOK_SIGNAL_INT, WEECHAT_HOOK_SIGNAL_POINTER +|======================================== + +[[common_tasks]] +Common tasks +------------ + +This chapter shows some common tasks, with examples. +Only partial things in API are used here, for full reference, see see +'WeeChat Plugin API Reference'. + +[[buffers]] +Buffers +~~~~~~~ + +[[buffers_display_messages]] +Display messages +^^^^^^^^^^^^^^^^ + +An empty string is often used to work with WeeChat core buffer. For other +buffers, you must give pointer (as string, see <>). + +Examples: + +[source,python] +---------------------------------------- +# display "hello" on core buffer +weechat.prnt("", "hello") + +# display prefix "==>" and message "hello" on current buffer +# (prefix and message must be separated by tab) +weechat.prnt(weechat.current_buffer(), "==>\thello") + +# display error message on core buffer (with error prefix) +weechat.prnt("", "%swrong arguments" % weechat.prefix("error")) + +# display message with color on core buffer +weechat.prnt("", "text %syellow on blue" % weechat.color("yellow,blue")) + +# search buffer and display message +# (full name of buffer is plugin.name, for example: "irc.freenode.#weechat") +buffer = weechat.buffer_search("irc", "freenode.#weechat") +weechat.prnt(buffer, "message on #weechat channel") + +# other solution to find an IRC buffer (better) +# (note that server and channel are separated by a comma) +buffer = weechat.info_get("irc_buffer", "freenode,#weechat") +weechat.prnt(buffer, "message on #weechat channel") +---------------------------------------- + +[NOTE] +Print function is called `print` in Perl/Ruby/Lua/Tcl and `prnt` in Python. + +[[buffers_send_text]] +Send text to buffer +^^^^^^^^^^^^^^^^^^^ + +You can send text or command to a buffer. This is exactly like if you type text +on command line and press [Enter]. + +Examples: + +[source,python] +---------------------------------------- +# execute command "/help" on core buffer +weechat.command("", "/help") + +# send "hello" to #weechat IRC channel (users on channel will see message) +buffer = weechat.info_get("irc_buffer", "freenode,#weechat") +weechat.command(buffer, "hello") +---------------------------------------- + +[[buffers_new]] +Create new buffer +^^^^^^^^^^^^^^^^^ + +You can create a new buffer in your script, then use it for displaying messages. + +Two callbacks can be called (they are optional): one for input data (when you +type some text and press [Enter] on buffer), the other is called when buffer is +closed (for example by `/buffer close`). + +Example: + +[source,python] +---------------------------------------- +# callback for data received in input +def buffer_input_cb(data, buffer, input_data): + # ... + return weechat.WEECHAT_RC_OK + +# callback called when buffer is closed +def buffer_close_cb(data, buffer): + # ... + return weechat.WEECHAT_RC_OK + +# create buffer +buffer = weechat.buffer_new("mybuffer", "buffer_input_cb", "", "buffer_close_cb", "") + +# set title +weechat.buffer_set(buffer, "title", "This is title for my buffer.") + +# disable logging, by setting local variable "no_log" to "1" +weechat.buffer_set(buffer, "localvar_set_no_log", "1") +---------------------------------------- + +[[buffers_properties]] +Buffer properties +^^^^^^^^^^^^^^^^^ + +You can read buffer properties, as string, integer or pointer. + +Examples: + +[source,python] +---------------------------------------- +buffer = weechat.current_buffer() + +number = weechat.buffer_get_integer(buffer, "number") +name = weechat.buffer_get_string(buffer, "name") +short_name = weechat.buffer_get_string(buffer, "short_name") +---------------------------------------- + +It is possible to add, read or delete local variables in buffer: + +[source,python] +---------------------------------------- +# add local variable +weechat.buffer_set(buffer, "localvar_set_myvar", "my_value") + +# read local variable +myvar = weechat.buffer_get_string(buffer, "localvar_myvar") + +# delete local variable +weechat.buffer_set(buffer, "localvar_del_myvar", "") +---------------------------------------- + +To see local variables of a buffer, do this command in WeeChat: + +---------------------------------------- +/buffer localvar +---------------------------------------- + +[[hooks]] +Hooks +~~~~~ + +[[hook_command]] +Add new command +^^^^^^^^^^^^^^^ + +Add a custom command with `hook_command`. You can use a custom completion +template to complete arguments of your command. + +Example: + +[source,python] +---------------------------------------- +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", "") +---------------------------------------- + +And then in WeeChat: + +---------------------------------------- +/help myfilter + +/myfilter arguments... +---------------------------------------- + +[[hook_timer]] +Add a timer +^^^^^^^^^^^ + +Add a timer with `hook_timer`. + +Example: + +[source,python] +---------------------------------------- +def timer_cb(data, remaining_calls): + # ... + return weechat.WEECHAT_RC_OK + +# timer called each minute when second is 00 +weechat.hook_timer(60 * 1000, 60, 0, "timer_cb", "") +---------------------------------------- + +[[hook_process]] +Run a background process +^^^^^^^^^^^^^^^^^^^^^^^^ + +You can run a background process with `hook_process`. Your callback will be +called when data is ready. It may be called many times. + +For the last call to your callback, 'rc' is set to 0 or positive value, it's +return code of command. + +Example: + +[source,python] +---------------------------------------- +# Display versions of Linux kernels. +kernel_txt = "" + +def kernel_process_cb(data, command, rc, stdout, stderr): + """ Callback reading command output. """ + global kernel_txt + if stdout != "": + kernel_txt += stdout + if int(rc) >= 0: + weechat.prnt("", kernel_txt) + return weechat.WEECHAT_RC_OK + +weechat.hook_process("python -c \"import urllib; " \ + "print urllib.urlopen('http://www.kernel.org/kdist/finger_banner').read()\"", + 10 * 1000, "kernel_process_cb", "") +---------------------------------------- + +[[config_options]] +Config / options +~~~~~~~~~~~~~~~~ + +[[config_options_set_script]] +Set options for script +^^^^^^^^^^^^^^^^^^^^^^ + +Function `config_is_set_plugin` is used to check if an option is set or not, +and `config_set_plugin` to set option. + +Example: + +[source,python] +---------------------------------------- +script_options = { + "option1" : "value1", + "option2" : "value2", + "option3" : "value3", +} +for option, default_value in script_options.iteritems(): + if not weechat.config_is_set_plugin(option): + weechat.config_set_plugin(option, default_value) +---------------------------------------- + +[[config_options_detect_changes]] +Detect changes +^^^^^^^^^^^^^^ + +You must use `hook_config` to be notified if user changes some script options. + +Example: + +[source,python] +---------------------------------------- +SCRIPT_NAME = "myscript" + +# ... + +def config_cb(data, option, value): + """ Callback called when a script option is changed. """ + # for example, read all script options to script variables... + # ... + return weechat.WEECHAT_RC_OK + +# ... + +weechat.hook_config("plugins.var.python." + SCRIPT_NAME + ".*", "config_cb", "") +# for other languages, change "python" with your language ("perl", "ruby", "lua" or "tcl") +---------------------------------------- + +[[config_options_weechat]] +Read WeeChat options +^^^^^^^^^^^^^^^^^^^^ + +Function `config_get` returns pointer to option. Then, depending on option type, +you must call `config_string`, `config_boolean`, `config_integer` or +`config_color`. + +[source,python] +---------------------------------------- +# string +weechat.prnt("", "value of option weechat.look.item_time_format is: %s" + % (weechat.config_string(weechat.config_get("weechat.look.item_time_format")))) + +# boolean +weechat.prnt("", "value of option weechat.look.day_change is: %d" + % (weechat.config_boolean(weechat.config_get("weechat.look.day_change")))) + +# integer +weechat.prnt("", "value of option weechat.look.scroll_page_percent is: %d" + % (weechat.config_integer(weechat.config_get("weechat.look.scroll_page_percent")))) + +# color +weechat.prnt("", "value of option weechat.color.chat_delimiters is: %s" + % (weechat.config_color(weechat.config_get("weechat.color.chat_delimiters")))) +---------------------------------------- + +[[irc]] +IRC +~~~ + +[[irc_catch_messages]] +Catch messages +^^^^^^^^^^^^^^ + +IRC plugin sends two signals for a message received (`xxx` is IRC internal +server name, `yyy` is IRC command name like JOIN, QUIT, PRIVMSG, 301, ..): + +xxxx,irc_in_yyy:: + signal sent before processing message + +xxx,irc_in2_yyy:: + signal sent after processing message + +[source,python] +---------------------------------------- +def join_cb(data, signal, signal_data): + # signal is for example: "freenode,irc_in2_join" + # signal_data is IRC message, for example: ":nick!user@host JOIN :#channel" + nick = weechat.info_get("irc_nick_from_host", signal_data) + server = signal.split(",")[0] + channel = signal_data.split(":")[-1] + buffer = weechat.info_get("irc_buffer", "%s,%s" % (server, channel)) + if buffer: + weechat.prnt(buffer, "Eheh, %s has joined this channel!" % nick) + return weechat.WEECHAT_RC_OK + +# it is useful here to use "*" as server, to catch JOIN messages on all IRC +# servers +weechat.hook_signal("*,irc_in2_join", "join_cb", "") +---------------------------------------- + +[[infos]] +Infos +~~~~~ + +[[infos_weechat_version]] +WeeChat version +^^^^^^^^^^^^^^^ + +The best way to check version is to ask "version_number" and make integer +comparison with hexidecimal version number. + +Example: + +[source,python] +---------------------------------------- +version = weechat.info_get("version_number", "") or 0 +if int(version) >= 0x00030200: + weechat.prnt("", "This is WeeChat 0.3.2 or newer") +else: + weechat.prnt("", "This is WeeChat 0.3.1 or older") +---------------------------------------- + +[NOTE] +Versions < = 0.3.1.1 return empty string for 'info_get("version_number")' so you +must check that value returned is *not* empty. + +To get version as string: + +[source,python] +---------------------------------------- +# this will display for example "Version 0.3.2" +weechat.prnt("", "Version %s" % weechat.info_get("version", "")) +---------------------------------------- + +[[infos_other]] +Other infos +^^^^^^^^^^^ + +[source,python] +---------------------------------------- +# WeeChat home directory, for example: "/home/xxxx/.weechat" +weechat.prnt("", "WeeChat home dir: %s" % weechat.info_get("weechat_dir", "")) + +# keyboard inactivity +weechat.prnt("", "Inactivity since %s seconds" % weechat.info_get("inactivity", "")) +---------------------------------------- + +[[infolists]] +Infolists +~~~~~~~~~ + +[[infolists_read]] +Read an infolist +^^^^^^^^^^^^^^^^ + +You can read infolist built by WeeChat or other plugins. + +Example: + +[source,python] +---------------------------------------- +# read infolist "buffer", to get list of buffers +infolist = weechat.infolist_get("buffer", "", "") +if infolist: + while weechat.infolist_next(infolist): + name = weechat.infolist_string(infolist, "name") + weechat.prnt("", "buffer: %s" % name) + weechat.infolist_free(infolist) +---------------------------------------- + +[IMPORTANT] +Don't forget to call `infolist_free` to free memory used by infolist, because +WeeChat will not automatically free memory. diff --git a/doc/fr/weechat_plugin_api.fr.txt b/doc/fr/weechat_plugin_api.fr.txt index 40ed05680..eb4bf0aa0 100644 --- a/doc/fr/weechat_plugin_api.fr.txt +++ b/doc/fr/weechat_plugin_api.fr.txt @@ -878,7 +878,7 @@ Paramètres : Valeur de retour : * tableau de chaînes, NULL en cas de problème (doit être libéré par un appel à - <<_weechat_string_free_split>> après utilisation) + <<_weechat_string_free_split,weechat_string_free_split>> après utilisation) Exemples en C : @@ -919,7 +919,8 @@ void weechat_string_free_split (char **split_string); Paramètres : -* 'split_string' : chaîne découpée par <<_weechat_string_split>> +* 'split_string' : chaîne découpée par + <<_weechat_string_split,weechat_string_split>> Exemple en C : @@ -947,7 +948,8 @@ char *weechat_string_build_with_split_string (char **split_string Paramètres : -* 'split_string' : chaîne découpée par la fonction <<_weechat_string_split>> +* 'split_string' : chaîne découpée par la fonction + <<_weechat_string_split,weechat_string_split>> * 'separator' : chaîne utilisée pour séparer les différentes chaînes Valeur de retour : @@ -989,7 +991,7 @@ Paramètres : Valeur de retour : * tableau de chaînes, NULL en cas de problème (doit être libéré par un appel à - <<_weechat_free_split_command>> après utilisation) + <<_weechat_free_split_command,weechat_free_split_command>> après utilisation) Exemple en C : @@ -1016,7 +1018,8 @@ void weechat_string_free_split_command (char **split_command); Paramètres : -* 'split_command' : commande éclatée par <<_weechat_string_split_command>> +* 'split_command' : commande éclatée par + <<_weechat_string_split_command,weechat_string_split_command>> Exemple en C : @@ -2534,9 +2537,10 @@ Valeur de retour : [NOTE] Le fichier n'est PAS créé sur le disque par cette fonction. Il sera créé par -l'appel à la fonction <<_weechat_write_config>>. Vous ne devriez appeler cette -fonction qu'après avoir créé les sections (avec <<_weechat_config_new_section>>) -et les options (avec <<_weechat_config_new_option>>). +l'appel à la fonction <<_weechat_write_config,weechat_write_config>>. +Vous ne devriez appeler cette fonction qu'après avoir créé les sections (avec +<<_weechat_config_new_section,weechat_config_new_section>>) et les options (avec +<<_weechat_config_new_option,weechat_config_new_option>>). Exemple en C : @@ -3321,7 +3325,7 @@ Paramètres : [NOTE] Vous pouvez affecter "null" à une option seulement si c'est autorisé pour -l'option (voir <<_weechat_config_new_option>>). +l'option (voir <<_weechat_config_new_option,weechat_config_new_option>>). Valeur de retour : @@ -5059,9 +5063,7 @@ def my_command_cb(data, buffer, args): return weechat.WEECHAT_RC_OK hook = weechat.hook_command("monfiltre", "description de monfiltre", - "[list] | [enable|disable|toggle [name]] | " - "[add name plugin.buffer tags regex] | " - "[del name|-all]", + "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]", "description des paramètres...", "list" " || enable %(filters_names)" @@ -5881,7 +5883,7 @@ Paramètres : * 'signal' : signal à envoyer * 'type_data' : type de données à envoyer avec le signal (voir - <<_weechat_hook_signal>>) + <<_weechat_hook_signal,weechat_hook_signal>>) * 'signal_data' : données envoyées avec le signal Exemple en C : @@ -5996,7 +5998,8 @@ Paramètres : ** 'const char *completion_item' : nom de la complétion ** 'struct t_gui_buffer *buffer' : tampon où la complétion est effectuée ** 'struct t_gui_completion *completion' : structure utilisée pour ajouter - les mots pour la complétion (voir <<_weechat_hook_completion_list_add>>) + les mots pour la complétion (voir + <<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>>) * 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par WeeChat @@ -6072,7 +6075,7 @@ Paramètres : ** 'WEECHAT_LIST_POS_BEGINNING' : au début de la liste ** 'WEECHAT_LIST_POS_END' : à la fin de la liste -Exemple en C : voir <<_weechat_hook_completion>>. +Exemple en C : voir <<_weechat_hook_completion,weechat_hook_completion>>. Script (Python) : @@ -8160,7 +8163,7 @@ Paramètres : * 'bar' : pointeur vers la barre * 'property' : name, hidden, priority, conditions, position, filling_top_bottom, filling_left_right, size, size_max, color_fg, color_delim, color_bg, - separator, items (voir <<_weechat_bar_new>>) + separator, items (voir <<_weechat_bar_new,weechat_bar_new>>) * 'value' : nouvelle valeur pour la propriété Valeur de retour : diff --git a/doc/fr/weechat_scripting.fr.txt b/doc/fr/weechat_scripting.fr.txt index 082309334..d224ffcbe 100644 --- a/doc/fr/weechat_scripting.fr.txt +++ b/doc/fr/weechat_scripting.fr.txt @@ -47,9 +47,9 @@ Quelques choses sont spécifiques aux langages : * tcl : ** les fonctions sont appelées par `weechat::xxx arg1 arg2 ...` -[[register]] -Register -~~~~~~~~ +[[register_function]] +Fonction register +~~~~~~~~~~~~~~~~~ Tous les scripts WeeChat doivent s'enregistrer ("register") auprès de WeeChat, et cela doit être la première fonction WeeChat appelée dans le script. @@ -74,11 +74,7 @@ Paramètres : est UTF-8, vous pouvez utiliser une valeur vide ici, car UTF-8 est le jeu de caractères par défaut) -[[script_example]] -Exemple de script -~~~~~~~~~~~~~~~~~ - -Exemple de script, pour chaque langage : +Exemple, pour chaque langage : * perl : @@ -142,11 +138,11 @@ Vous devez utiliser la commande, dépendant du langage : Vous pouvez faire un lien dans le répertoire 'langage/autoload' pour charger automatiquement le script quand WeeChat démarre. -Par exemple en perl : +Par exemple en Python : ---------------------------------------- -$ cd ~/.weechat/perl/autoload -$ ln -s ../script.pl +$ cd ~/.weechat/python/autoload +$ ln -s ../script.py ---------------------------------------- [[differences_with_c_api]] @@ -160,7 +156,7 @@ chaque fonction de l'API : prototype, paramètres, valeurs de retour, exemples. Il est important de bien faire la différence entre une 'extension' et un 'script' : une 'extension' est un fichier binaire compilé et chargé avec la commande `/plugin`, tandis qu'un 'script' est un fichier texte chargé par une -extension comme 'perl' par la commande `perl`. +extension comme 'pyhton' par la commande `/python`. Quand votre script 'test.py' appelle une fonction de l'API WeeChat, le chemin est le suivant : @@ -180,6 +176,7 @@ est inversé : WeeChat core -------> extension plugin (python.so) -------> test.py ........................................ +[[pointers]] Pointeurs ~~~~~~~~~ @@ -209,6 +206,7 @@ si votre pointeur est correct ou pas. Il est de votre responsabilité de vérifier que vous donnez un pointeur valide, sinon vous pourriez voir un joli rapport de crash ;) +[[callbacks]] Callbacks ~~~~~~~~~ @@ -239,206 +237,538 @@ API script Pour plus d'informations sur les fonctions de l'API, merci de consulter la 'Référence API Extension WeeChat'. +[[script_api_functions]] Fonctions ~~~~~~~~~ Liste des fonctions de l'API script : -* général : -** 'register' -* extensions : -** 'plugin_get_name' -* chaînes : -** 'charset_set' -** 'iconv_to_internal' -** 'iconv_from_internal' -** 'gettext' -** 'ngettext' -** 'string_remove_color' -* répertoires : -** 'mkdir_home' -** 'mkdir' -** 'mkdir_parents' -* listes triées : -** 'list_new' -** 'list_add' -** 'list_search' -** 'list_casesearch' -** 'list_get' -** 'list_set' -** 'list_next' -** 'list_prev' -** 'list_string' -** 'list_size' -** 'list_remove' -** 'list_remove_all' -** 'list_free' -* fichiers de configuration : -** 'config_new' -** 'config_new_section' -** 'config_search_section' -** 'config_new_option' -** 'config_search_option' -** 'config_string_to_boolean' -** 'config_option_reset' -** 'config_option_set' -** 'config_option_set_null' -** 'config_option_unset' -** 'config_option_rename' -** 'config_option_is_null' -** 'config_option_default_is_null' -** 'config_boolean' -** 'config_boolean_default' -** 'config_integer' -** 'config_integer_default' -** 'config_string' -** 'config_string_default' -** 'config_color' -** 'config_color_default' -** 'config_write_option' -** 'config_write_line' -** 'config_write' -** 'config_read' -** 'config_reload' -** 'config_option_free' -** 'config_section_free_options' -** 'config_section_free' -** 'config_free' -** 'config_get' -** 'config_get_plugin' -** 'config_is_set_plugin' -** 'config_set_plugin' -** 'config_unset_plugin' -* affichage : -** 'prefix' -** 'color' -** 'print' (pour python : 'prnt') -** 'print_date_tags' (pour python : 'prnt_date_tags') -** 'print_y' (pour python : 'prnt_y') -** 'log_print' -* hooks : -** 'hook_command' -** 'hook_command_run' -** 'hook_timer' -** 'hook_fd' -** 'hook_process' -** 'hook_connect' -** 'hook_print' -** 'hook_signal' -** 'hook_signal_send' -** 'hook_config' -** 'hook_completion' -** 'hook_completion_list_add' -** 'hook_modifier' -** 'hook_modifier_exec' -** 'hook_info' -** 'hook_infolist' -** 'unhook' -** 'unhook_all' -* tampons : -** 'buffer_new' -** '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' -* fenêtres : -** 'current_window' -** 'window_get_integer' -** 'window_get_pointer' -** 'window_set_title' -* liste des pseudos : -** 'nicklist_add_group' -** 'nicklist_search_group' -** 'nicklist_add_nick' -** 'nicklist_search_nick' -** 'nicklist_remove_group' -** 'nicklist_remove_nick' -** 'nicklist_remove_all' -* barres : -** 'bar_item_search' -** 'bar_item_new' -** 'bar_item_update' -** 'bar_item_remove' -** 'bar_search' -** 'bar_new' -** 'bar_set' -** 'bar_update' -** 'bar_remove' -* commandes : -** 'command' -* infos : -** 'info_get' -* infolists : -** 'infolist_new' -** 'infolist_new_item' -** 'infolist_new_var_integer' -** 'infolist_new_var_string' -** 'infolist_new_var_pointer' -** 'infolist_new_var_time' -** 'infolist_get' -** 'infolist_next' -** 'infolist_prev' -** 'infolist_reset_item_cursor' -** 'infolist_fields' -** 'infolist_integer' -** 'infolist_string' -** 'infolist_pointer' -** 'infolist_time' -** 'infolist_free' -* mise à jour : -** 'upgrade_new' -** 'upgrade_write_object' -** 'upgrade_read' -** 'upgrade_close' +[width="100%",cols="^1,10",options="header"] +|======================================== +| Catégorie | Fonctions +| général | + register +| extensions | + plugin_get_name +| chaînes | + charset_set, iconv_to_internal, iconv_from_internal, + + gettext, ngettext, + string_remove_color, + + string_is_command_char, string_input_for_buffer +| répertoires | + mkdir_home, mkdir, mkdir_parents +| listes triées | + list_new, list_add, list_search, list_casesearch, list_get, list_set, + list_next, list_prev, list_string, list_size, list_remove, list_remove_all, + list_free +| fichiers de configuration | + config_new, config_new_section, config_search_section, config_new_option, + config_search_option, + + config_string_to_boolean, config_option_reset, config_option_set, + config_option_set_null, config_option_unset, config_option_rename, + config_option_is_null, config_option_default_is_null, + + config_boolean, config_boolean_default, config_integer, config_integer_default, + config_string, config_string_default, config_color, config_color_default, + + config_write_option, config_write_line, config_write, config_read, + config_reload, + + config_option_free, config_section_free_options, config_section_free, + config_free, + + config_get, config_get_plugin, config_is_set_plugin, config_set_plugin, + config_unset_plugin +| affichage | + prefix, color, print (for python: prnt), print_date_tags (for python: + prnt_date_tags), print_y (for python: prnt_y), log_print +| hooks | + hook_command, hook_command_run, hook_timer, hook_fd, hook_process, + hook_connect, hook_print, hook_signal, hook_signal_send, hook_config, + hook_completion, hook_completion_list_add, hook_modifier, hook_modifier_exec, + hook_info, hook_infolist, unhook, unhook_all +| tampons | + buffer_new, 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 +| fenêtres | + current_window, window_get_integer, window_get_string, window_get_pointer, + window_set_title +| liste des pseudos | + nicklist_add_group, nicklist_search_group, nicklist_add_nick, + nicklist_search_nick, nicklist_remove_group, nicklist_remove_nick, + nicklist_remove_all +| barres | + bar_item_search, bar_item_new, bar_item_update, bar_item_remove, bar_search, + bar_new, bar_set, bar_update, bar_remove +| commandes | + command +| infos | + info_get +| infolists | + infolist_new, infolist_new_item, infolist_new_var_integer, + infolist_new_var_string, infolist_new_var_pointer, infolist_new_var_time, + + infolist_get, infolist_next, infolist_prev, infolist_fields, infolist_integer, + infolist_string, infolist_pointer, infolist_time, infolist_free +| mise à jour | + upgrade_new, upgrade_write_object, upgrade_read, upgrade_close +|======================================== +[[script_api_constants]] Constantes ~~~~~~~~~~ Liste des constantes de l'API script : -* 'WEECHAT_RC_OK' -* 'WEECHAT_RC_OK_EAT' -* 'WEECHAT_RC_ERROR' -* 'WEECHAT_CONFIG_READ_OK' -* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' -* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' -* 'WEECHAT_CONFIG_WRITE_OK' -* 'WEECHAT_CONFIG_WRITE_ERROR' -* 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR' -* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' -* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' -* 'WEECHAT_CONFIG_OPTION_SET_ERROR' -* 'WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND' -* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' -* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' -* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' -* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' -* 'WEECHAT_LIST_POS_SORT' -* 'WEECHAT_LIST_POS_BEGINNING' -* 'WEECHAT_LIST_POS_END' -* 'WEECHAT_HOTLIST_LOW' -* 'WEECHAT_HOTLIST_MESSAGE' -* 'WEECHAT_HOTLIST_PRIVATE' -* 'WEECHAT_HOTLIST_HIGHLIGHT' -* 'WEECHAT_HOOK_PROCESS_RUNNING' -* 'WEECHAT_HOOK_PROCESS_ERROR' -* 'WEECHAT_HOOK_CONNECT_OK' -* 'WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND' -* 'WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND' -* 'WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED' -* 'WEECHAT_HOOK_CONNECT_PROXY_ERROR' -* 'WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR' -* 'WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR' -* 'WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR' -* 'WEECHAT_HOOK_CONNECT_MEMORY_ERROR' -* 'WEECHAT_HOOK_SIGNAL_STRING' -* 'WEECHAT_HOOK_SIGNAL_INT' -* 'WEECHAT_HOOK_SIGNAL_POINTER' +[width="100%",cols="^1,10",options="header"] +|======================================== +| Catégorie | Constantes +| codes retour | + WEECHAT_RC_OK, WEECHAT_RC_OK_EAT, WEECHAT_RC_ERROR +| fichiers de configuration | + WEECHAT_CONFIG_READ_OK, WEECHAT_CONFIG_READ_MEMORY_ERROR, + WEECHAT_CONFIG_READ_FILE_NOT_FOUND, WEECHAT_CONFIG_WRITE_OK, + WEECHAT_CONFIG_WRITE_ERROR, WEECHAT_CONFIG_WRITE_MEMORY_ERROR, + + WEECHAT_CONFIG_OPTION_SET_OK_CHANGED, WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE, + WEECHAT_CONFIG_OPTION_SET_ERROR, WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND, + WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET, WEECHAT_CONFIG_OPTION_UNSET_OK_RESET, + WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED, WEECHAT_CONFIG_OPTION_UNSET_ERROR +| listes triées | + WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING, WEECHAT_LIST_POS_END +| hotlist | + WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, + WEECHAT_HOTLIST_HIGHLIGHT +| hook process | + WEECHAT_HOOK_PROCESS_RUNNING, WEECHAT_HOOK_PROCESS_ERROR +| hook connect | + WEECHAT_HOOK_CONNECT_OK, WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND, + WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND, WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED, + WEECHAT_HOOK_CONNECT_PROXY_ERROR, WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR, + WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR, WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR, + WEECHAT_HOOK_CONNECT_MEMORY_ERROR +| hook signal | + WEECHAT_HOOK_SIGNAL_STRING, WEECHAT_HOOK_SIGNAL_INT, WEECHAT_HOOK_SIGNAL_POINTER +|======================================== + +[[common_tasks]] +Tâches courantes +---------------- + +Ce chapitre montre quelques tâches courantes, avec des exemples. +Seule une partie de l'API est utilisée ici, pour une référence complète, voir la +'Référence API Extension WeeChat'. + +[[buffers]] +Tampons +~~~~~~~ + +[[buffers_display_messages]] +Afficher des messages +^^^^^^^^^^^^^^^^^^^^^ + +Une chaîne vide est souvent utilisée pour travailler avec le tampon core WeeChat. +Pour les autres tampons, vous devez passer un pointeur (sous forme de chaîne, +voir <>). + +Exemples : + +[source,python] +---------------------------------------- +# afficher "bonjour" sur le tampon core +weechat.prnt("", "bonjour") + +# afficher le préfixe "==>" et le message "bonjour" sur le tampon courant +# (le préfixe et le message doivent être séparés par une tabulation) +weechat.prnt(weechat.current_buffer(), "==>\tbonjour") + +# afficher un message d'erreur sur le tampon core (avec le préfixe d'erreur) +weechat.prnt("", "%smauvais paramètres" % weechat.prefix("error")) + +# afficher un message avec de la couleur sur le tampon core +weechat.prnt("", "texte %sjaune sur bleu" % weechat.color("yellow,blue")) + +# chercher un tampon et afficher un message +# (le nom complet d'un tampon est extension.nom, par exemple : "irc.freenode.#weechat") +buffer = weechat.buffer_search("irc", "freenode.#weechat") +weechat.prnt(buffer, "message sur le canal #weechat") + +# autre solution pour chercher un tampon IRC (meilleure) +# (notez que le serveur et le canal sont séparés par une virgule) +buffer = weechat.info_get("irc_buffer", "freenode,#weechat") +weechat.prnt(buffer, "message sur le canal #weechat") +---------------------------------------- + +[NOTE] +La fonction d'affichage est appelée `print` en Perl/Ruby/Lua/Tcl et `prnt` en +Python. + +[[buffers_send_text]] +Envoyer du texte au tampon +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Vous pouvez envoyer du texte ou une commande à un tampon. C'est exactement comme +si vous tapiez le texte sur la ligne de commande et que vous pressiez [Enter]. + +Exemples : + +[source,python] +---------------------------------------- +# exécuter la commande "/help" sur le tampon core +weechat.command("", "/help") + +# envoyer "bonjour" au canal IRC #weechat (les utilisateurs sur le canal verront le message) +buffer = weechat.info_get("irc_buffer", "freenode,#weechat") +weechat.command(buffer, "bonjour") +---------------------------------------- + +[[buffers_new]] +Créer un nouveau tampon +^^^^^^^^^^^^^^^^^^^^^^^ + +Vous pouvez créer un nouveau tampon dans votre script, et l'utiliser pour +afficher des messages. + +Deux "callbacks" peuvent être appelés (ils sont optionnels) : un pour les données +en entrée (quand vous tapez du texte et pressez [Enter] sur le tampon), l'autre +est appelé lorsque le tampon est fermé (par exemple avec `/buffer close`). + +Exemple : + +[source,python] +---------------------------------------- +# callback pour les données reçues en entrée +def buffer_input_cb(data, buffer, input_data): + # ... + return weechat.WEECHAT_RC_OK + +# callback appelé lorsque le tampon est fermé +def buffer_close_cb(data, buffer): + # ... + return weechat.WEECHAT_RC_OK + +# créer le tampon +buffer = weechat.buffer_new("montampon", "buffer_input_cb", "", "buffer_close_cb", "") + +# définir le titre +weechat.buffer_set(buffer, "title", "Ceci est le titre du tampon.") + +# désactiver l'enregistrement (log), en définissant la variable locale "no_log" à "1" +weechat.buffer_set(buffer, "localvar_set_no_log", "1") +---------------------------------------- + +[[buffers_properties]] +Propriétés du tampon +^^^^^^^^^^^^^^^^^^^^ + +Vous pouvez lire des propriétés du tampon, sous forme de chaîne, entier ou +pointeur. + +Exemples : + +[source,python] +---------------------------------------- +buffer = weechat.current_buffer() + +number = weechat.buffer_get_integer(buffer, "number") +name = weechat.buffer_get_string(buffer, "name") +short_name = weechat.buffer_get_string(buffer, "short_name") +---------------------------------------- + +Il est possible d'ajouter, lire ou supprimer des variables locales dans le +tampon : + +[source,python] +---------------------------------------- +# ajouter une variable locale +weechat.buffer_set(buffer, "localvar_set_myvar", "my_value") + +# lire une variable locale +myvar = weechat.buffer_get_string(buffer, "localvar_myvar") + +# supprimer une variable locale +weechat.buffer_set(buffer, "localvar_del_myvar", "") +---------------------------------------- + +Pour voir les variables locales d'un tampon, exécutez cette commande dans +WeeChat : + +---------------------------------------- +/buffer localvar +---------------------------------------- + +[[hooks]] +Hooks +~~~~~ + +[[hook_command]] +Ajouter une nouvelle commande +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoutez une nouvelle commande avec `hook_command`. Vous pouvez utiliser une +complétion personnalisée pour compléter les paramètres de votre commande. + +Exemple : + +[source,python] +---------------------------------------- +def my_command_cb(data, buffer, args): + # ... + return weechat.WEECHAT_RC_OK + +hook = weechat.hook_command("monfiltre", "description de mon filtre", + "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]", + "description des paramètres...", + "list" + " || enable %(filters_names)" + " || disable %(filters_names)" + " || toggle %(filters_names)" + " || add %(filters_names) %(buffers_plugins_names)|*" + " || del %(filters_names)|-all", + "my_command_cb", "") +---------------------------------------- + +Puis sous WeeChat : + +---------------------------------------- +/help monfiltre + +/monfiltre paramètres... +---------------------------------------- + +[[hook_timer]] +Ajouter un timer +^^^^^^^^^^^^^^^^ + +Ajoutez un timer avec `hook_timer`. + +Exemple : + +[source,python] +---------------------------------------- +def timer_cb(data, remaining_calls): + # ... + return weechat.WEECHAT_RC_OK + +# timer appelé chaque minute quand la seconde est 00 +weechat.hook_timer(60 * 1000, 60, 0, "timer_cb", "") +---------------------------------------- + +[[hook_process]] +Lancer un processus en tâche de fond +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Vous pouvez lancer un processus en tâche de fond avec `hook_process`. Votre +"callback" sera appelé quand des données seront prêtes. Il peut être appelé +plusieurs fois. + +Pour le dernier appel à votre "callback", 'rc' est positionné à 0 ou une valeur +positive, c'est le code retour de la commande. + +Exemple : + +[source,python] +---------------------------------------- +# Afficher la version des noyaux Linux. +kernel_txt = "" + +def kernel_process_cb(data, command, rc, stdout, stderr): + """ Callback qui lit la sortie de la commande. """ + global kernel_txt + if stdout != "": + kernel_txt += stdout + if int(rc) >= 0: + weechat.prnt("", kernel_txt) + return weechat.WEECHAT_RC_OK + +weechat.hook_process("python -c \"import urllib; " \ + "print urllib.urlopen('http://www.kernel.org/kdist/finger_banner').read()\"", + 10 * 1000, "kernel_process_cb", "") +---------------------------------------- + +[[config_options]] +Config / options +~~~~~~~~~~~~~~~~ + +[[config_options_set_script]] +Définir des options pour le script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +La fonction `config_is_set_plugin` est utilisée pour vérifier si une option est +définie ou pas, et `config_set_plugin` pour définir une option. + +Exemple : + +[source,python] +---------------------------------------- +script_options = { + "option1" : "valeur1", + "option2" : "valeur2", + "option3" : "valeur3", +} +for option, default_value in script_options.iteritems(): + if not weechat.config_is_set_plugin(option): + weechat.config_set_plugin(option, default_value) +---------------------------------------- + +[[config_options_detect_changes]] +Détecter des changements +^^^^^^^^^^^^^^^^^^^^^^^^ + +Vous devez utiliser `hook_config` pour être notifié si l'utilisateur modifie +certaines options du script. + +Exemple : + +[source,python] +---------------------------------------- +SCRIPT_NAME = "monscript" + +# ... + +def config_cb(data, option, value): + """ Callback appelé lorsqu'une option du script est modifiée. """ + # par exemple, relire toutes les options du script dans des variables du script... + # ... + return weechat.WEECHAT_RC_OK + +# ... + +weechat.hook_config("plugins.var.python." + SCRIPT_NAME + ".*", "config_cb", "") +# pour les autres languages, remplacez "python" par le language ("perl", "ruby", "lua" ou "tcl") +---------------------------------------- + +[[config_options_weechat]] +Lire les options WeeChat +^^^^^^^^^^^^^^^^^^^^^^^^ + +La fonction `config_get` retourne un pointeur vers une option. Ensuite, en +fonction du type de l'option, il faut appeler `config_string`, `config_boolean`, +`config_integer` ou `config_color`. + +[source,python] +---------------------------------------- +# chaîne +weechat.prnt("", "la valeur de l'option weechat.look.item_time_format est : %s" + % (weechat.config_string(weechat.config_get("weechat.look.item_time_format")))) + +# booléen +weechat.prnt("", "la valeur de l'option weechat.look.day_change est : %d" + % (weechat.config_boolean(weechat.config_get("weechat.look.day_change")))) + +# entier +weechat.prnt("", "la valeur de l'option weechat.look.scroll_page_percent est : %d" + % (weechat.config_integer(weechat.config_get("weechat.look.scroll_page_percent")))) + +# couleur +weechat.prnt("", "la valeur de l'option weechat.color.chat_delimiters est : %s" + % (weechat.config_color(weechat.config_get("weechat.color.chat_delimiters")))) +---------------------------------------- + +[[irc]] +IRC +~~~ + +[[irc_catch_messages]] +Intercepter des messages +^^^^^^^^^^^^^^^^^^^^^^^^ + +L'extension IRC envoie deux signaux pour un message reçu (`xxx` est le nom +interne du serveur IRC, `yyy` est le nom de la commande IRC comme JOIN, QUIT, +PRIVMSG, 301, ..): + +xxxx,irc_in_yyy:: + signal envoyé avant traitement du message + +xxx,irc_in2_yyy:: + message sent après traitement du message + +[source,python] +---------------------------------------- +def join_cb(data, signal, signal_data): + # signal est par exemple : "freenode,irc_in2_join" + # signal_data est le message IRC, par exemple : ":nick!user@host JOIN :#canal" + nick = weechat.info_get("irc_nick_from_host", signal_data) + server = signal.split(",")[0] + channel = signal_data.split(":")[-1] + buffer = weechat.info_get("irc_buffer", "%s,%s" % (server, channel)) + if buffer: + weechat.prnt(buffer, "Eheh, %s a rejoint le canal !" % nick) + return weechat.WEECHAT_RC_OK + +# il est pratique ici d'utiliser "*" comme serveur, pour intercepter les +# messages JOIN de tous les serveurs IRC +weechat.hook_signal("*,irc_in2_join", "join_cb", "") +---------------------------------------- + +[[infos]] +Infos +~~~~~ + +[[infos_weechat_version]] +Version de WeeChat +^^^^^^^^^^^^^^^^^^ + +Le meilleur moyen de vérifier la version est de demander "version_number" et de +faire une comparaison entre nombre entiers avec la version hexadécimale de la +version. + +Exemple : + +[source,python] +---------------------------------------- +version = weechat.info_get("version_number", "") or 0 +if int(version) >= 0x00030200: + weechat.prnt("", "C'est WeeChat 0.3.2 ou plus récent") +else: + weechat.prnt("", "C'est WeeChat 0.3.1 ou plus ancien") +---------------------------------------- + +[NOTE] +Les versions < = 0.3.1.1 retournent une chaîne vide pour +'info_get("version_number")', donc vous devez vérifier que la valeur de retour +n'est *pas* vide. + +Pour obtenir la version sous forme de chaîne : + +[source,python] +---------------------------------------- +# ceci affichera par exemple "Version 0.3.2" +weechat.prnt("", "Version %s" % weechat.info_get("version", "")) +---------------------------------------- + +[[infos_other]] +Autres infos +^^^^^^^^^^^^ + +[source,python] +---------------------------------------- +# répertoire de WeeChat, par exemple : "/home/xxxx/.weechat" +weechat.prnt("", "Répertoire WeeChat : %s" % weechat.info_get("weechat_dir", "")) + +# inactivité clavier +weechat.prnt("", "Inactivité depuis %s secondes" % weechat.info_get("inactivity", "")) +---------------------------------------- + +[[infolists]] +Infolists +~~~~~~~~~ + +[[infolists_read]] +Lire une infolist +^^^^^^^^^^^^^^^^^ + +Vous pouvez lire une infolist construite par WeeChat ou d'autres extensions. + +Exemple : + +[source,python] +---------------------------------------- +# lecture de l'infolist "buffer", pour avoir la liste des tampons +infolist = weechat.infolist_get("buffer", "", "") +if infolist: + while weechat.infolist_next(infolist): + name = weechat.infolist_string(infolist, "name") + weechat.prnt("", "buffer: %s" % name) + weechat.infolist_free(infolist) +---------------------------------------- + +[IMPORTANT] +N'oubliez pas d'appeler `infolist_free` pour libérer la mémoire utilisée par +l'infolist, car WeeChat ne libère par automatiquement cette mémoire.