From 885df965e50855cc07db442ea920ff524b860d25 Mon Sep 17 00:00:00 2001 From: Sebastien Helleu Date: Thu, 6 Nov 2008 09:47:52 +0100 Subject: Rename developer doc (-devel to -dev) --- doc/en/dev/plugin_api.en.xml | 4728 ++++++++++++++++++++++++++++++++++++++ doc/en/dev/plugin_scripts.en.xml | 2849 +++++++++++++++++++++++ doc/en/dev/plugins.en.xml | 250 ++ doc/en/dev/weechat_dev.en.xml | 101 + 4 files changed, 7928 insertions(+) create mode 100644 doc/en/dev/plugin_api.en.xml create mode 100644 doc/en/dev/plugin_scripts.en.xml create mode 100644 doc/en/dev/plugins.en.xml create mode 100644 doc/en/dev/weechat_dev.en.xml (limited to 'doc/en/dev') diff --git a/doc/en/dev/plugin_api.en.xml b/doc/en/dev/plugin_api.en.xml new file mode 100644 index 000000000..8d90cb480 --- /dev/null +++ b/doc/en/dev/plugin_api.en.xml @@ -0,0 +1,4728 @@ + + + + +
+ Plugin API + + + +
+ Strings + + + Many string functions below are already available thru standard C + functions, but it's recommended to use functions in this API because + they are ok with UTF-8 and locale. + + +
+ weechat_charset_set + + + Prototype: + + void weechat_charset_set (const char *charset) + + + + Set new plugin charset. + + + Arguments: + + + + : new charset to use + + + + + + Example: + weechat_charset_set (plugin, "iso-8859-1"); + +
+ +
+ weechat_iconv_to_internal + + + Prototype: + + void weechat_iconv_to_internal (const char *charset, + const char *string) + + + + Convert string to WeeChat internal charset (UTF-8). + + + Arguments: + + + + : charset to convert + + + + + : string to convert + + + + + + Return value: converted string. + + + Note: result has to be free by a call to "free" after use. + + + Example: + char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à"); + +
+ +
+ weechat_iconv_from_internal + + + Prototype: + + void weechat_iconv_from_internal (const char *charset, + const char *string) + + + + Convert string from internal WeeChat charset (UTF-8) to another. + + + Arguments: + + + + : target charset + + + + + : string to convert + + + + + + Return value: converted string. + + + Note: result has to be free by a call to "free" after use. + + + Example: + char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à"); + +
+ +
+ weechat_gettext + + + Prototype: + + char *weechat_gettext (const char *string) + + + + Return translated string (depends on local language). + + + Arguments: + + + + : string to translate + + + + + + Return value: translated string. + + + Example: + char *str = weechat_gettext ("hello !"); + +
+ +
+ weechat_ngettext + + + Prototype: + + char *weechat_ngettext (const char *string, const char *plural, + int count) + + + + Return translated string, using single or plural form, according to + count. + + + Arguments: + + + + : string to translate (single form) + + + + + : string to translate (plural form) + + + + + : used to choose between single and plural + form + + + + + + Return value: translated string. + + + Example: + char *str = weechat_ngettext ("file", "files", num_files); + +
+ +
+ weechat_strndup + + + Prototype: + + char *weechat_strndup (const char *string, int length) + + + + Return duplicated string, with max "length" chars. + + + Arguments: + + + + : string to duplicate + + + + + : max chars to duplicate + + + + + + Return value: duplicated string. + + + Note: result has to be free by a call to "free" after use. + + + Example: + char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */ + +
+ +
+ weechat_string_tolower + + + Prototype: + + char *weechat_string_tolower (const char *string) + + + + Convert UTF-8 string to lower case. + + + Arguments: + + + + : string to convert + + + + + + Return value: none. + + + Example: + weechat_string_tolower ("AbCdEé"); /* result: "abcdeé" */ + +
+ +
+ weechat_string_toupper + + + Prototype: + + char *weechat_string_toupper (const char *string) + + + + Convert UTF-8 string to upper case. + + + Arguments: + + + + : string to convert + + + + + + Return value: none. + + + Example: + weechat_string_toupper ("AbCdEé"); /* result: "ABCDEé" */ + +
+ +
+ weechat_strcasecmp + + + Prototype: + + int weechat_strcasecmp (const char *string1, const char *string2) + + + + Locale and case independent string comparison. + + + Arguments: + + + + : first string for comparison + + + + + : second string for comparison + + + + + + Return value: difference between two strings: negative if + string1 < string2, zero if string1 == string2, positive if + string1 > string2 + + + Example: + int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */ + +
+ +
+ weechat_strncasecmp + + + Prototype: + + int weechat_strncasecmp (const char *string1, const char *string2, + int max) + + + + Locale and case independent string comparison, for "max" chars. + + + Arguments: + + + + : first string for comparison + + + + + : second string for comparison + + + + + : max number of chars for comparison + + + + + + Return value: difference between two strings: negative if + string1 < string2, zero if string1 == string2, positive if + string1 > string2 + + + Example: + int diff = weechat_strncasecmp ("aaa", "CCC", 2); /* == -2 */ + +
+ +
+ weechat_strcmp_ignore_chars + + + Prototype: + + int weechat_strcmp_ignore_chars (const char *string1, + const char *string2, const char *chars_ignored, int case_sensitive) + + + + Locale (and optionally case independent) string comparison, ignoring + some chars. + + + Arguments: + + + + : first string for comparison + + + + + : second string for comparison + + + + + : string with chars to ignore + + + + + : 1 for case sensitive comparison, + 0 otherwise + + + + + + Return value: difference between two strings: negative if + string1 < string2, zero if string1 == string2, positive if + string1 > string2 + + + Example: + int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */ + +
+ +
+ weechat_strcasestr + + + Prototype: + + int weechat_strcasestr (const char *string, const char *search) + + + + Locale and case independent string search. + + + Arguments: + + + + : string + + + + + : string to search in "string" + + + + + + Return value: pointer to string found, or NULL if not found + + + Example: + char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */ + +
+ +
+ weechat_string_match + + + Prototype: + + int weechat_string_match (const char *string, const char *mask, + int case_sensitive) + + + + Check if a string matches a mask. Mask may begin or end with "*" (no + other "*" are allowed inside mask). + + + Arguments: + + + + : string + + + + + : mask + + + + + : 1 for case sensitive search, + otherwise 0 + + + + + + Return value: 1 if string matches mask, otherwise 0. + + + Examples: + +int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */ +int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */ +int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */ + + +
+ +
+ weechat_string_replace + + + Prototype: + + char *weechat_string_replace (const char *string, const char *search, + const char *replace) + + + + Replace "search" string by new one in a string. + + + Arguments: + + + + : string + + + + + : string to replace + + + + + : replacement for "search" string + + + + + + Return value: string with "search" replaced by "replace". + + + Note: result has to be free by a call to "free" after use. + + + Example: + char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */ + +
+ +
+ weechat_string_remove_quotes + + + Prototype: + + char *weechat_string_remove_quotes (const char *string, + const char *quotes) + + + + Remove quotes at beginning/end of string (ignore spaces if there are + before first quote or after last quote). + + + Arguments: + + + + : string + + + + + : string with list of quotes + + + + + + Return value: string without quotes at beginning/end. + + + Note: result has to be free by a call to "free" after use. + + + Example: + char *str = weechat_string_remove_quotes (string, " 'abc' ", "'"); /* result: "abc" */ + +
+ +
+ weechat_string_strip + + + Prototype: + + char *weechat_string_strip (const char *string, int left, int right, + const char *chars) + + + + Strip chars at beginning and/or end of string. + + + Arguments: + + + + : string + + + + + : strip left chars if different from 0 + + + + + : strip right chars if different from 0 + + + + + : string with chars to strip + + + + + + Return value: stripped string. + + + Note: result has to be free by a call to "free" after use. + + + Example: + char *str = weechat_strip (string, " ", 0, 1); /* remove spaces at end of string */ + +
+ +
+ weechat_string_has_highlight + + + Prototype: + + char *weechat_string_has_highlight (const char *string, + const char highlight_words) + + + + Check if a string has highlights, using list of highlight words. + + + Arguments: + + + + : string + + + + + : list of highlight words, + separated by comma + + + + + + Return value: 1 if string has one or more highlights, 0 otherwise. + + + Example: + if (weechat_string_has_highlight (string, "word1,word2")) ... + +
+ +
+ weechat_string_explode + + + Prototype: + + char **weechat_string_explode (const char *string, + const char *separators, int keep_eol, int num_items_max, + int *num_items) + + + + Explode a string according to one or more delimiter(s). + + + Arguments: + + + + : string to explode + + + + + : delimiters used for explosion + + + + + : if different from 0, then each argument + will contain all string until end of line (see example below) + + + + + : maximum number of items + created (0 = no limit) + + + + + : pointer to int which will + contain number of items created + + + + + + Return value: array of strings, NULL if problem. + + + Note: result has to be free by a call to "weechat_string_free_exploded" + after use. + + + Examples: + +char **argv; +int argc; +argv = weechat_string_explode ("abc de fghi", " ", 0, 0, &argc); +/* result: argv[0] == "abc" + argv[1] == "de" + argv[2] == "fghi" + argv[3] == NULL + argc == 3 +*/ +weechat_string_free_exploded (argv); + +argv = weechat_string_explode ("abc de fghi", " ", 1, 0, &argc); +/* result: argv[0] == "abc de fghi" + argv[1] == "de fghi" + argv[2] == "fghi" + argv[3] == NULL + argc == 3 +*/ +weechat_string_free_exploded (argv); + + +
+ +
+ weechat_string_free_exploded + + + Prototype: + + void weechat_string_free_exploded (char **exploded_string) + + + + Free memory used by a string explosion. + + + Arguments: + + + + : string exploded by + "weechat_string_explode" function + + + + + + Return value: none. + + + Example: + +char *argv; +int argc; +argv = weechat_string_explode (string, " ", 0, 0, &argc); +... +weechat_string_free_exploded (, argv); + + +
+ +
+ weechat_string_build_with_exploded + + + Prototype: + + char **weechat_string_build_with_exploded (char **exploded_string, + const char *separator) + + + + Build a string with exploded string. + + + Arguments: + + + + : string exploded by + "weechat_string_explode" function + + + + + : string used to separate strings + + + + + + Return value: string built with exploded string. + + + Note: result has to be free by a call to "free" after use. + + + Example: + +char **argv; +int argc; +argv = weechat_string_explode ("abc def ghi", " ", 0, 0, &argc); +char *string = weechat_string_build_with_exploded (argv, ";"); +/* string == "abc;def;ghi" */ + + +
+ +
+ weechat_string_split_command + + + Prototype: + + char **weechat_string_split_command (const char *command, + char separator) + + + + Split a list of commands separated by 'separator' (which can be escaped + by '\' in string). + + + Arguments: + + + + : command to split + + + + + : separator + + + + + + Return value: array of strings, NULL if problem. + + + Note: result has to be free by a call to + "weechat_string_free_splitted_command" after use. + + + Example: + char **argv = weechat_string_split_command ("/command1;/command2", ';'); + +
+ +
+ weechat_string_free_splitted_command + + + Prototype: + + void weechat_string_free_splitted_command (char **splitted_command) + + + + Free memory used by a splitted command. + + + Arguments: + + + + : command splitted by + "weechat_string_split_commaand" function + + + + + + Return value: none. + + + Example: + +char **argv = weechat_string_split_command ("/command1;/command2", ';'); +... +weechat_string_free_splitted_command (argv); + + +
+ +
+ + + +
+ UTF-8 + + + Some UTF-8 string functions. + + +
+ weechat_utf8_has_8bits + + + Prototype: + + int weechat_utf8_has_8bits (const char *string) + + + + Check if a string has 8-bits chars. + + + Arguments: + + + + : string + + + + + + Return value: 1 if string has 8-buts chars, 0 if only 7-bits chars. + + + Example: + if (weechat_utf8_has_8bits (string)) ... + +
+ +
+ weechat_utf8_is_valid + + + Prototype: + + int weechat_utf8_is_valid (const char *string, char **error) + + + + Check if a string is UTF-8 valid. + + + Arguments: + + + + : string + + + + + : if not NULL, it is set with first non + valid UTF-8 char in string, if any + + + + + + Return value: 1 if UTF-8 string is valid, 0 otherwise. + + + Example: + +char *error; +if (weechat_utf8_is_valid (string, &error)) ... + + +
+ +
+ weechat_utf8_normalize + + + Prototype: + + void weechat_utf8_normalize (const char *string, char replacement) + + + + Normalize UTF-8 string: remove non UTF-8 chars and replace them by a + char + + + Arguments: + + + + : string + + + + + : replacement char for non UTF-8 chars + + + + + + Return value: none. + + + Example: + weechat_utf8_normalize (string, '?'); + +
+ +
+ weechat_utf8_prev_char + + + Prototype: + + char *weechat_utf8_prev_char (const char *string_start, + const char *string) + + + + Return previous UTF-8 char in a string. + + + Arguments: + + + + : start of string (function will not + return a char before this pointer) + + + + + : pointer to string (must be >= + string_start) + + + + + + Return value: pointer to previous UTF-8 char, NULL if not found + (start of string reached) + + + Example: + char *prev_char = weechat_utf8_prev_char (string, ptr_in_string); + +
+ +
+ weechat_utf8_next_char + + + Prototype: + + char *weechat_utf8_next_char (const char *string) + + + + Return next UTF-8 char in a string. + + + Arguments: + + + + : string + + + + + + Return value: pointer to next UTF-8 char, NULL if not found + (end of string reached) + + + Example: + char *next_char = weechat_utf8_next_char (string); + +
+ +
+ weechat_utf8_char_size + + + Prototype: + + int weechat_utf8_char_size (const char *string) + + + + Return UTF-8 char size (in bytes). + + + Arguments: + + + + : string + + + + + + Return value: UTF-8 char size (in bytes). + + + Example: + int char_size = weechat_utf8_char_size ("être"); /* == 2 */ + +
+ +
+ weechat_utf8_strlen + + + Prototype: + + int weechat_utf8_strlen (const char *string) + + + + Return UTF-8 string length (multi-byte char is considered as 1 char). + + + Arguments: + + + + : string + + + + + + Return value: UTF-8 string length (number of real chars). + + + Example: + int length = weechat_utf8_strlen ("chêne"); /* == 5 */ + +
+ +
+ weechat_utf8_strnlen + + + Prototype: + + int weechat_utf8_strnlen (const char *string, int bytes) + + + + Return UTF-8 string length (multi-byte char is considered as 1 char), + for max bytes in string + + + Arguments: + + + + : string + + + + + : max bytes in string + + + + + + Return value: UTF-8 string length (number of real chars). + + + Example: + int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */ + +
+ +
+ weechat_utf8_strlen_screen + + + Prototype: + + int weechat_utf8_strlen_screen (const char *string) + + + + Return number of chars needed on screen to display UTF-8 string. + + + Arguments: + + + + : string + + + + + + Return value: number of chars needed on screen to display UTF-8 string. + + + Example: + int length_on_screen = weechat_utf8_strlen_screen ("东"); /* == 2 */ + +
+ +
+ weechat_utf8_charcasecmp + + + Prototype: + + int weechat_utf8_charcasecmp (const char *string1, + const char *string2) + + + + Compare two UTF-8 chars (case is ignored). + + + Arguments: + + + + : first string for comparison + + + + + : second string for comparison + + + + + + Return value: difference between first char of each string: negative if + char1 < char2, zero if char1 == char2, positive if char1 > char2 + + + Example: + if (weechat_utf8_charcasecmp (string1, string2) != 0) ... + +
+ +
+ weechat_utf8_char_size_screen + + + Prototype: + + int weechat_utf8_char_size_screen (const char *string) + + + + Return number of chars needed on screen to display UTF-8 char. + + + Arguments: + + + + : string + + + + + + Return value: number of chars needed on screen to display UTF-8 char. + + + Example: + int length_on_screen = weechat_utf8_char_size_screen (string) + +
+ +
+ weechat_utf8_add_offset + + + Prototype: + + char *weechat_utf8_add_offset (const char *string, int offset) + + + + Move forward N chars in an UTF-8 string. + + + Arguments: + + + + : string + + + + + : number of chars + + + + + + Return value: pointer to string, N chars after (NULL if it's not + reachable). + + + Example: + char *ptr = weechat_utf8_add_offset ("chêne", 3); /* points to "ne" */ + +
+ +
+ weechat_utf8_real_pos + + + Prototype: + + char *weechat_utf8_real_pos (const char *string, int pos) + + + + Get real position in UTF-8 string. + + + Arguments: + + + + : string + + + + + : position in chars + + + + + + Return value: real position (in bytes) for "pos" chars in string. + + + Example: + int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */ + +
+ +
+ weechat_utf8_pos + + + Prototype: + + char *weechat_utf8_pos (const char *string, int real_pos) + + + + Get position in UTF-8 string. + + + Arguments: + + + + : string + + + + + : position in bytes + + + + + + Return value: position (in chars) for "real_pos" bytes in string. + + + Example: + int pos = weechat_utf8_real_pos ("chêne", 4); /* == 3 */ + +
+ +
+ + + +
+ Directories + + + Some functions related to directories. + + +
+ weechat_mkdir_home + + + Prototype: + + int weechat_mkdir_home (char *directory, int mode) + + + + Create a directory in WeeChat home. + + + Arguments: + + + + : directory to create + + + + + : mode for new directory + + + + + + Return value: 1 if directory was successfully created, 0 if an + error occurred. + + + Example: + if (!weechat_mkdir_home ("temp")) ... + +
+ +
+ weechat_mkdir + + + Prototype: + + int weechat_mkdir (char *directory, int mode) + + + + Create a directory. + + + Arguments: + + + + : directory to create + + + + + : mode for new directory + + + + + + Return value: 1 if directory was successfully created, 0 if an + error occurred. + + + Example: + if (!weechat_mkdir ("/tmp/mydir")) ... + +
+ +
+ weechat_exec_on_files + + + Prototype: + + void weechat_exec_on_files (const char *directory, void *data, + int (*callback)(void *data, const char *filename)) + + + + Find files in a directory and execute a callback on each file. + + + Arguments: + + + + : directory for searching files + + + + + : pointer given to callback when calling it + found + + + + + : function called for each file + found + + + + + + Return value: none. + + + Example: + +int callback (void *data, const char *filename) +{ + /* ... */ + return 1; +} +... +plugin->exec_on_files (plugin, "/tmp", &callback); + + +
+ +
+ + + +
+ Util + + + Some useful functions. + + +
+ weechat_timeval_cmp + + + Prototype: + + int weechat_timeval_cmp (struct timeval *tv1, struct timeval *tv2) + + + + Compare 2 timeval structures. + + + Arguments: + + + + : first timeval structure + + + + + : second timeval structure + + + + + + Return value: -1 if tv1 < char2, zero if tv1 == tv2, +1 if tv1 > + tv2 + + + Example: + if (weechat_timeval_cmp (&tv1, &tv2) > 0) ... + +
+ +
+ weechat_timeval_diff + + + Prototype: + + long weechat_timeval_diff (struct timeval *tv1, struct timeval *tv2) + + + + Return difference (in milliseconds) between 2 timeval structures. + + + Arguments: + + + + : first timeval structure + + + + + : second timeval structure + + + + + + Return value: difference in milliseconds. + + + Example: + long diff = weechat_timeval_diff (&tv1, &tv2); + +
+ +
+ weechat_timeval_add + + + Prototype: + + void weechat_timeval_add (struct timeval *tv, long interval) + + + + Add interval (in milliseconds) to a timeval structure. + + + Arguments: + + + + : timeval structure + + + + + : interval (in milliseconds) + + + + + + Return value: none. + + + Example: + weechat_timeval_add (&tv, 2000); /* add 2 seconds */ + +
+ +
+ + To be continued... + + + +
diff --git a/doc/en/dev/plugin_scripts.en.xml b/doc/en/dev/plugin_scripts.en.xml new file mode 100644 index 000000000..a4aa2ea7a --- /dev/null +++ b/doc/en/dev/plugin_scripts.en.xml @@ -0,0 +1,2849 @@ + + + + +
+ Scripts plugins + + + Four plugins are provided with WeeChat to use script languages: + Perl, Python, Ruby and Lua. + + +
+ Load / unload scripts + + + Scripts are loaded and unloaded with /perl, + /python, /ruby and + /lua commands + (type /help in WeeChat for help about commands). + + + + Examples: + + + + Load a Perl script: + /perl load /tmp/test.pl + + + + + List all loaded Perl scripts: + /perl + + + + + Load a Python script: + /python load /tmp/test.py + + + + + List all loaded Python scripts: + /python + + + + + Load a Ruby script: + /ruby load /tmp/test.rb + + + + + List all loaded Ruby scripts: + /ruby + + + + + Load a Lua script: + /lua load /tmp/test.lua + + + + + List all loaded Lua scripts: + /lua + + + + + +
+ +
+ Syntax by language + +
+ Perl + + + In a WeeChat Perl script, all API functions and variables are + prefixed by "weechat::". + Example: +weechat::register("test", "1.0", "end_test", "WeeChat perl script"); + + +
+ +
+ Python + + + A WeeChat Python script has to start by importing weechat: + import weechat + + + + All API functions and variables are prefixed by + "weechat.". + Example: +weechat.register("test", "1.0", "end_test", "WeeChat python script") + + +
+ +
+ Ruby + + + In a WeeChat Ruby script, all code has to be in functions. + So for main code, you have to define a + "weechat_init" function, which is automatically + called when script is loaded by WeeChat. Example: + +def weechat_init + Weechat.register("test", "1.0", "end_test", "WeeChat ruby script") + Weechat.add_command_handler("command", "my_command") + return Weechat::PLUGIN_RC_OK +end + +def my_command(server, args) + Weechat.print("my command") + return Weechat::PLUGIN_RC_OK +end + + + + + All API functions are prefixed by + "Weechat." and variables by + "Weechat::". + + +
+ +
+ Lua + + + In a WeeChat Lua script, all API functions are prefixed by + "weechat.". + Variables are prefixed by "weechat." and + suffixed by "()". + Example: + +function message_handler(server, args) + weechat.print("I am a message handler") + return weechat.PLUGIN_RC_OK() +end + + + +
+ +
+ +
+ WeeChat / scripts API + +
+ register + + + Perl prototype: + + weechat::register(name, version, end_function, description, + [charset]); + + + + Python prototype: + + weechat.register(name, version, end_function, description, + [charset]) + + + + Ruby prototype: + + Weechat.register(name, version, end_function, description, + [charset]) + + + + Lua prototype: + + weechat.register(name, version, end_function, description, + [charset]) + + + + This is first function to call in script. + All WeeChat scripts have to call this function. + + + Arguments: + + + + : unique name to identify script + (each script must have unique name) + + + + + : script version + + + + + : function called when script is + unloaded (optional parameter, empty string means nothing is + called at the end) + + + + + : short description of script + + + + + : charset used by script, you should + set this if script is not written with UTF-8 + + + + + + Return value: 1 if script was registered, 0 if an error occured. + + + Examples: + +# perl +weechat::register("test", "1.0", "end_test", "Test script!", "ISO-8859-1"); + +# python +weechat.register("test", "1.0", "end_test", "Test script!", "ISO-8859-1") + +# ruby +Weechat.register("test", "1.0", "end_test", "Test script!", "ISO-8859-1") + +-- lua +weechat.register("test", "1.0", "end_test", "Test script!", "ISO-8859-1") + + +
+ +
+ set_charset + + + Perl prototype: + + weechat::set_charset(charset); + + + + Python prototype: + + weechat.set_charset(charset) + + + + Ruby prototype: + + Weechat.set_charset(charset) + + + + Lua prototype: + + weechat.set_charset(charset) + + + + Set new script charset. + + + Arguments: + + + + : new script charset + + + + + + Return value: 1 if new charset was set, 0 if an error occured. + + + Examples: + +# perl +weechat::set_charset("ISO-8859-1"); + +# python +weechat.set_charset("ISO-8859-1") + +# ruby +Weechat.set_charset("ISO-8859-1") + +-- lua +weechat.set_charset("ISO-8859-1") + + +
+ +
+ print + + + Perl prototype: + + weechat::print(message, [channel, [server]]) + + + + Python prototype: + + weechat.prnt(message, [channel, [server]]) + + + + Ruby prototype: + + Weechat.print(message, [channel, [server]]) + + + + Lua prototype: + + weechat.print(message, [channel, [server]]) + + + + Display a message on a WeeChat buffer, identified by server + and channel. + + + Arguments: + + + + : message + + + + + : name of channel to find buffer + for message display + + + + + : internal name of server to find + buffer for message display + + + + + + To display colored text, see . + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::print("message"); +weechat::print("message", "#weechat"); +weechat::print("message", "#weechat", "freenode"); +weechat::print("test: \x0305 red \x0F normal"); + +# python +weechat.prnt("message") +weechat.prnt("message", "#weechat") +weechat.prnt("message", "#weechat", "freenode") + +# ruby +Weechat.print("message") +Weechat.print("message", "#weechat") +Weechat.print("message", "#weechat", "freenode") + +-- lua +weechat.print("message") +weechat.print("message", "#weechat") +weechat.print("message", "#weechat", "freenode") + + +
+ +
+ print_server + + + Perl prototype: + + weechat::print_server(message) + + + + Python prototype: + + weechat.print_server(message) + + + + Ruby prototype: + + Weechat.print_server(message) + + + + Lua prototype: + + weechat.print_server(message) + + + + Display a message on server buffer. + + + Arguments: + + + + : message + + + + + + To display colored text, see . + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::print_server("message"); +weechat::print_server("test: \x0305 red \x0F normal"); + +# python +weechat.print_server("message") + +# ruby +Weechat.print_server("message") + +-- lua +weechat.print_server("message") + + +
+ +
+ log + + + Perl prototype: + + weechat::log(message, [channel, [server]]); + + + + Python prototype: + + weechat.log(message, [channel, [server]]) + + + + Ruby prototype: + + Weechat.log(message, [channel, [server]]) + + + + Lua prototype: + + weechat.log(message, [channel, [server]]) + + + + Write a message in log file for a server or a channel. + + + Arguments: + + + + : message + + + + + : name of channel to find buffer + for log + + + + + : internal name of server to find + buffer for log + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::log("message", "#weechat", "freenode"); + +# python +weechat.log("message", "#weechat", "freenode") + +# ruby +Weechat.log("message", "#weechat", "freenode") + +-- lua +weechat.log("message", "#weechat", "freenode") + + +
+ +
+ add_message_handler + + + Perl prototype: + + weechat::add_message_handler(message, function); + + + + Python prototype: + + weechat.add_message_handler(message, function) + + + + Ruby prototype: + + Weechat.add_message_handler(message, function) + + + + Lua prototype: + + weechat.add_message_handler(message, function) + + + + Add an IRC message handler, called when an IRC message is + received. + + + Arguments: + + + + : name of IRC message. To know list + of IRC messages, please consult RFCs + 1459 + and + 2812. + Moreover you can use a special name, prefixed by "weechat_" + to catch special events (see + ). + + + + + : function called when message is + received + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::add_message_handler ("privmsg", "my_function"); +sub my_function +{ + weechat::print("server=$_[0]"); + ($null, $channel, $message) = split ":",$_[1],3; + ($mask, $null, $channel) = split " ", $channel; + weechat::print("mask=$mask, channel=$channel, msg=$message"); + return weechat::PLUGIN_RC_OK; +} + +# python +weechat.add_message_handler ("privmsg", "my_function") +def my_function(server, args): + weechat.prnt("server="+server) + null, channel, message = string.split(args, ":", 2) + mask, null, channel = string.split(string.strip(channel), " ", 2) + weechat.prnt("mask="+mask+", canal="+channel+", message="+message) + return weechat.PLUGIN_RC_OK + +# ruby +Weechat.add_message_handler("privmsg", "my_function") +def my_function(server, args) + Weechat.print("server=#{server}, args=#{args}") + return Weechat::PLUGIN_RC_OK +end + +-- lua +weechat.add_message_handler ("privmsg", "my_function") +function my_function(server, args) + weechat.print("server=" .. server .. ", args=" .. args) + return weechat.PLUGIN_RC_OK() +end + + + + Note: function called when message is received has to return + one of following values: + + + + PLUGIN_RC_KO: function failed + + + + + PLUGIN_RC_OK: function successfully + completed + + + + + PLUGIN_RC_OK_IGNORE_WEECHAT: message + will not be sent to WeeChat + + + + + PLUGIN_RC_OK_IGNORE_PLUGINS: message + will not be sent to other plugins + + + + + PLUGIN_RC_OK_IGNORE_ALL: message + will not be sent to WeeChat neither other plugins + + + + + PLUGIN_RC_OK_WITH_HIGHLIGHT: function + successfully completed and make "highlight" on received + message + + + + +
+ +
+ add_command_handler + + + Perl prototype: + + weechat::add_command_handler(command, function, + [description, arguments, arguments_description, + completion_template]); + + + + Python prototype: + + weechat.add_command_handler(command, function, + [description, arguments, arguments_description, + completion_template]) + + + + Ruby prototype: + + Weechat.add_command_handler(command, function, + [description, arguments, arguments_description, + completion_template]) + + + + Lua prototype: + + weechat.add_command_handler(command, function, + [description, arguments, arguments_description, + completion_template]) + + + + Add a WeeChat command handler, called when user uses command + (for example /command). + + + Arguments: + + + + : the new command name, which + may be an existing command (be careful, replaced command + will not be available until script is unloaded) + + + + + : function called when command + is executed + + + + + : short description of command + arguments (displayed by /help command) + + + + + : long description + of command arguments (displayed by /help command) + + + + + : template for + completion, like "abc|%w def|%i" which + means "abc" or a WeeChat command for first argument, + "def" or IRC command for second. + (see ) + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::add_command_handler("command", "my_command"); +sub my_command +{ + weechat::print("server= $_[0], args: $_[1]"); + return weechat::PLUGIN_RC_OK; +} + +# python +weechat.add_command_handler("command", "my_command") +def my_command(server, args): + weechat.prnt("server="+server+", args="+args) + return weechat.PLUGIN_RC_OK + +# ruby +Weechat.add_command_handler("command", "my_command") +def my_command(server, args) + Weechat.print("server=#{server}, args=#{args}") + return Weechat::PLUGIN_RC_OK +end + +-- lua +weechat.add_command_handler("command", "my_command") +def my_command(server, args) + weechat.print("server="..server..", args="..args) + return weechat.PLUGIN_RC_OK() +end + + + + Notes: function called when command is executed has to return + one of following values: + + + + PLUGIN_RC_KO : function failed + + + + + PLUGIN_RC_OK : function successfully + completed + + + + +
+ +
+ add_timer_handler + + + Perl prototype: + + weechat::add_timer_handler(interval, function); + + + + Python prototype: + + weechat.add_timer_handler(interval, function) + + + + Ruby prototype: + + Weechat.add_timer_handler(interval, function) + + + + Lua prototype: + + weechat.add_timer_handler(interval, function) + + + + Add a timer handler which periodically calls a function. + + + Arguments: + + + + : interval (in seconds) between + two calls of function. + + + + + : function called + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::add_timer_handler(60, "my_timer"); +sub my_timer +{ + weechat::print("this is timer handler"); + return weechat::PLUGIN_RC_OK; +} + +# python +weechat.add_timer_handler(60, "my_timer") +def my_timer(): + weechat.prnt("this is timer handler") + return weechat.PLUGIN_RC_OK + +# ruby +Weechat.add_timer_handler(60, "my_timer") +def my_timer() + Weechat.print("this is timer handler") + return Weechat::PLUGIN_RC_OK +end + +-- lua +weechat.add_timer_handler(60, "my_timer") +function my_timer() + weechat.print("this is timer handler") + return weechat.PLUGIN_RC_OK() +end + + + + Note: function called has to return one of following values: + + + + PLUGIN_RC_KO: function failed + + + + + PLUGIN_RC_OK: function successfully + completed + + + + +
+ +
+ add_keyboard_handler + + + Perl prototype: + + weechat::add_keyboard_handler(function); + + + + Python prototype: + + weechat.add_keyboard_handler(function) + + + + Ruby prototype: + + Weechat.add_keyboard_handler(function) + + + + Lua prototype: + + weechat.add_keyboard_handler(function) + + + + Add a keyboard handler, called for any key pressed. + + + Arguments: + + + + : function called + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::add_keyboard_handler("my_keyboard"); +sub my_keyboard +{ + my $key = shift; + my $input_before = shift; + my $input_after = shift; + weechat::print("keyboard handler: key = '$key', " + ."input before = '$input_before' " + ."after = '$input_after'"); + return weechat::PLUGIN_RC_OK; +} + +# python +weechat.add_keyboard_handler("my_keyboard") +def my_keyboard(key, input_before, input_after): + weechat.prnt("keyboard handler: key = '%s', " \ + "input before = '%s' after = '%s'" + %(key, input_before, input_after)) + return weechat.PLUGIN_RC_OK + +# ruby +Weechat.add_keyboard_handler("my_keyboard") +def my_keyboard(key, input_before, input_after) + Weechat.print("keyboard handler: key = '#{key}', " \ + "input before = '#{input_before}' " \ + "after = '#{input_after}'") + return Weechat::PLUGIN_RC_OK +end + +-- lua +weechat.add_keyboard_handler("my_keyboard") +function my_keyboard(key, input_before, input_after) + weechat.print("keyboard handler: key = '"..key.. + "', input before = '"..input_before.. + "' after = '"..input_after.."'") + return weechat.PLUGIN_RC_OK() +end + + + + Note: function called has to return one of following values: + + + + PLUGIN_RC_KO: function failed + + + + + PLUGIN_RC_OK: function successfully + completed + + + + +
+ +
+ add_event_handler + + + Perl prototype: + + weechat::add_event_handler(event, function); + + + + Python prototype: + + weechat.add_event_handler(event, function) + + + + Ruby prototype: + + Weechat.add_event_handler(event, function) + + + + Lua prototype: + + weechat.add_event_handler(event, function) + + + + Add an event handler, called when an event happens. + + + Arguments: + + + + : event + (see ) + + + + + : function called + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::add_event_handler("buffer_open", "my_event"); +sub my_event +{ + weechat::print("buffer open"); + return weechat::PLUGIN_RC_OK; +} + +# python +weechat.add_event_handler("buffer_open", "my_event") +def my_event(): + weechat.prnt("buffer open") + return weechat.PLUGIN_RC_OK + +# ruby +Weechat.add_event_handler("buffer_open", "my_event") +def my_event() + Weechat.print("buffer open") + return Weechat::PLUGIN_RC_OK +end + +-- lua +weechat.add_event_handler("buffer_open", "my_event") +function my_event() + weechat.print("buffer open") + return weechat.PLUGIN_RC_OK() +end + + + + Note: function called has to return one of following values: + + + + PLUGIN_RC_KO: function failed + + + + + PLUGIN_RC_OK: function successfully + completed + + + + +
+ +
+ remove_handler + + + Perl prototype: + + weechat::remove_handler(name, function); + + + + Python prototype: + + weechat.remove_handler(name, function) + + + + Ruby prototype: + + Weechat.remove_handler(name, function) + + + + Lua prototype: + + weechat.remove_handler(name, function) + + + + Remove a message or command handler. + + + Arguments: + + + + : name of IRC message or command + + + + + : function + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::remove_handler("command", "my_command"); + +# python +weechat.remove_handler("command", "my_command") + +# ruby +Weechat.remove_handler("command", "my_command") + +-- lua +weechat.remove_handler("command", "my_command") + + +
+ +
+ remove_timer_handler + + + Perl prototype: + + weechat::remove_timer_handler(function); + + + + Python prototype: + + weechat.remove_timer_handler(function) + + + + Ruby prototype: + + Weechat.remove_timer_handler(function) + + + + Lua prototype: + + weechat.remove_timer_handler(function) + + + + Remove a timer handler. + + + Arguments: + + + + : function + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::remove_timer_handler("my_timer"); + +# python +weechat.remove_timer_handler("my_timer") + +# ruby +Weechat.remove_timer_handler("my_timer") + +-- lua +weechat.remove_timer_handler("my_timer") + + +
+ +
+ remove_keyboard_handler + + + Perl prototype: + + weechat::remove_keyboard_handler(function); + + + + Python prototype: + + weechat.remove_keyboard_handler(function) + + + + Ruby prototype: + + Weechat.remove_keyboard_handler(function) + + + + Lua prototype: + + weechat.remove_keyboard_handler(function) + + + + Remove a keyboard handler. + + + Arguments: + + + + : function + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::remove_keyboard_handler("my_keyboard"); + +# python +weechat.remove_keyboard_handler("my_keyboard") + +# ruby +Weechat.remove_keyboard_handler("my_keyboard") + +-- lua +weechat.remove_keyboard_handler("my_keyboard") + + +
+ +
+ remove_event_handler + + + Perl prototype: + + weechat::remove_event_handler(function); + + + + Python prototype: + + weechat.remove_event_handler(function) + + + + Ruby prototype: + + Weechat.remove_event_handler(function) + + + + Lua prototype: + + weechat.remove_event_handler(function) + + + + Remove an event handler. + + + Arguments: + + + + : function + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::remove_event_handler("my_event"); + +# python +weechat.remove_event_handler("my_event") + +# ruby +Weechat.remove_event_handler("my_event") + +-- lua +weechat.remove_event_handler("my_event") + + +
+ +
+ add_modifier + + + Perl prototype: + + weechat::add_modifier(type, message, function); + + + + Python prototype: + + weechat.add_modifier(type, message, function) + + + + Ruby prototype: + + Weechat.add_modifier(type, message, function) + + + + Lua prototype: + + weechat.add_modifier(type, message, function) + + + + Add a message modifier. + + + Arguments: + + + + : modifier type: + + + + + Type + Description + + + + + irc_in + called for incoming IRC messages + + + irc_user + + called for each user message (or command) (before + WeeChat parses message) + + + + irc_out + + called for outgoing messages, immediately before + sending it to IRC server (this includes messages + sent automatically by WeeChat to server) + + + + + + + + + + : name of IRC message (used only for + types "irc_in" and "irc_out"). + To know list of IRC messages, please consult + RFCs + 1459 + and + 2812. + Moreover, special value "*" means all messages (no filter). + + + + + : function called + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::add_modifier("irc_in", "privmsg", "mod_in"); +weechat::add_modifier("irc_out", "privmsg", "mod_out"); +sub mod_in +{ + return "$_[1] [modifier IN]"; +} +sub mod_out +{ + return "$_[1] [modifier OUT]"; +} + +# python +weechat.add_modifier("irc_in", "privmsg", "mod_in") +weechat.add_modifier("irc_out", "privmsg", "mod_out") +def mod_in(serveur, args): + return args + " [modifier IN]" +def mod_out(serveur, args): + return args + " [modifier OUT]" + +# ruby +Weechat.add_modifier("irc_in", "privmsg", "mod_in") +Weechat.add_modifier("irc_out", "privmsg", "mod_out") +def mod_in(server, args) + return args + " [modifier IN]" +end +def mod_out(server, args) + return args + " [modifier OUT]" +end + +-- lua +weechat.add_modifier("irc_in", "privmsg", "mod_in") +weechat.add_modifier("irc_out", "privmsg", "mod_out") +function mod_in(server, args) + return args .. " [modifier IN]" +end +function mod_out(server, args) + return args .. " [modifier OUT]" +end + + +
+ +
+ remove_modifier + + + Perl prototype: + + weechat::remove_modifier(type, message, function); + + + + Python prototype: + + weechat.remove_modifier(type, message, function) + + + + Ruby prototype: + + Weechat.remove_modifier(type, message, function) + + + + Lua prototype: + + weechat.remove_modifier(type, message, function) + + + + Remove a message modifier. + + + Arguments: + + + + : modifier type + + + + + : message managed by modifier + + + + + : function + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::remove_modifier("irc_in", "privmsg", "mod_in"); + +# python +weechat.remove_modifier("irc_in", "privmsg", "mod_in") + +# ruby +Weechat.remove_modifier("irc_in", "privmsg", "mod_in") + +-- lua +weechat.remove_modifier("irc_in", "privmsg", "mod_in") + + +
+ +
+ command + + + Perl prototype: + + weechat::command(command, [channel, [server]]); + + + + Python prototype: + + weechat.command(command, [channel, [server]]) + + + + Ruby prototype: + + Weechat.command(command, [channel, [server]]) + + + + Lua prototype: + + weechat.command(command, [channel, [server]]) + + + + Execute a WeeChat command (or send a message to a channel). + + + Arguments: + + + + : command + + + + + : name of channel for executing + command + + + + + : internal name of server for + executing command + + + + + + Return value: 1 if success, 0 if an error occurred. + + + Examples: + +# perl +weechat::command("hello everybody!"); +weechat::command("/kick toto please leave this channel", "#weechat"); +weechat::command("/nick newnick", "", "freenode"); + +# python +weechat.command("hello everybody!") +weechat.command("/kick toto please leave this channel", "#weechat") +weechat.command("/nick newnick", "", "freenode") + +# ruby +Weechat.command("hello everybody!") +Weechat.command("/kick toto please leave this channel", "#weechat") +Weechat.command("/nick newnick", "", "freenode") + +-- lua +weechat.command("hello everybody!") +weechat.command("/kick toto please leave this channel", "#weechat") +weechat.command("/nick newnick", "", "freenode") + + +
+ +
+ get_info + + + Perl prototype: + + weechat::get_info(name, [server]); + + + + Python prototype: + + weechat.get_info(name, [server]) + + + + Ruby prototype: + + Weechat.get_info(name, [server]) + + + + Lua prototype: + + weechat.get_info(name, [server]) + + + + Return an info about WeeChat or a channel. + + + Arguments: + + + + : name of info to read + (see ) + + + + + : internal name of server for + reading info (if needed) + + + + + + Return value: information asked, empty string if an error + occurred. + + + Examples: + +# perl +$version = get_info("version"); +$nick = get_info("nick", "freenode"); + +# python +version = weechat.get_info("version") +nick = weechat.get_info("nick", "freenode") + +# ruby +version = Weechat.get_info("version") +nick = Weechat.get_info("nick", "freenode") + +-- lua +version = weechat.get_info("version") +nick = weechat.get_info("nick", "freenode") + + +
+ +
+ get_dcc_info + + + Perl prototype: + + weechat::get_dcc_info(); + + + + Python prototype: + + weechat.get_dcc_info() + + + + Ruby prototype: + + Weechat.get_dcc_info() + + + + Lua prototype: + + weechat.get_dcc_info() + + + + Return list of DCC currently active or finished. + + + Return value: list of DCC + (see ). + + + Examples: + +# perl +my @dccs = weechat::get_dcc_info(); +if (@dccs) +{ + foreach my $dcc (@dccs) + { + while (my ($key, $value) = each %$dcc) + { + weechat::print("$key = '$value'"); + } + } +} +else +{ + weechat::print("no DCC"); +} + +# python +dccs = weechat.get_dcc_info() +if dccs != None: + if dccs == []: + weechat.prnt("no DCC") + else: + for d in dccs: + for b in d.keys(): + weechat.prnt("%s = '%s'" %(b, d[b])) +else: + weechat.prnt("error while getting DCC") + +# ruby +dccs = Weechat.get_dcc_info() +if dccs != nil + if dccs == [] + Weechat.print("no DCC") + else + dccs.each do |m| + m.each do |key, value| + Weechat.print("#{key} = '#{value}'") + end + end + end +else + Weechat.print("error while getting DCC") +end + +-- lua +dccs = weechat.get_dcc_info() +if dccs ~= nil then + if dccs then + dcc, dccinfos = next (dccs, nil) + while (dcc) do + key, value = next (dccinfos, nil) + while (key) do + weechat.print(key.." = '"..value.."'") + key, value = next (dccinfos, key) + end + dcc, dccinfos = next (dccs, dcc) + end + else + weechat.print("no DCC") + end +else + weechat.print("error while getting DCC") +end + + +
+ +
+ get_server_info + + + Perl prototype: + + weechat::get_server_info(); + + + + Python prototype: + + weechat.get_server_info() + + + + Ruby prototype: + + Weechat.get_server_info() + + + + Lua prototype: + + weechat.get_server_info() + + + + Return list of IRC servers (connected or not). + + + Return value: list of servers + (see ). + + + Examples: + +# perl +my $servers = weechat::get_server_info(); +if ($servers) +{ + while (my ($srvname, $srvinfos) = each %$servers) + { + while ( my ($key, $value) = each %$srvinfos) + { + weechat::print("$srvname -> $key = '$value'"); + } + } +} +else +{ + weechat::print("no server"); +} + +# python +servers = weechat.get_server_info() +if servers != None: + if servers == {}: + weechat.prnt("no server") + else: + for s in servers: + for i in servers[s]: + weechat.prnt("%s -> %s = '%s'" % (s, i, str(servers[s][i]))) +else: + weechat.prnt("error while getting servers") + +# ruby +servers = Weechat.get_server_info() +if servers != nil + if servers == [] + Weechat.print("no server") + else + servers.each do |n, s| + s.each do |key, value| + Weechat.print("#{n} -> #{key} = '#{value}'") + end + end + end +else + Weechat.print("error while getting servers") +end + +-- lua +servers = weechat.get_server_info() +if servers ~= nil then + if servers then + srv, srvinfos = next (servers, nil) + while (srv) do + key, value = next (srvinfos, nil) + while (key) do + weechat.print(srv.." -> "..key.." = '"..value.."'") + key, value = next (srvinfos, key) + end + srv, srvinfos = next (servers, srv) + end + else + weechat.print("no server") + end +else + weechat.print("error while getting servers") +end + + +
+ +
+ get_channel_info + + + Perl prototype: + + weechat::get_channel_info(server); + + + + Python prototype: + + weechat.get_channel_info(server) + + + + Ruby prototype: + + Weechat.get_channel_info(server) + + + + Lua prototype: + + weechat.get_channel_info(server) + + + + Return list of IRC channels for a server. + + + Return value: list of IRC channels for server + (see ). + + + Examples: + +# perl +my $channels = weechat::get_channel_info(weechat::get_info("server")); +if ($channels) +{ + while (my ($channame, $chaninfos) = each %$channels) + { + while (my ($key, $value) = each %$chaninfos) + { + weechat::print("$channame -> $key = '$value'"); + } + } +} +else +{ + weechat::print("no channel"); +} + +# python +chans = weechat.get_channel_info(weechat.get_info("server")) +if chans != None: + if chans == {}: + weechat.prnt("no channel") + else: + for s in chans: + for i in chans[s]: + weechat.prnt("%s -> %s = '%s'" % (s, i, str(chans[s][i]))) +else: + weechat.prnt("error while getting channels") + +# ruby +channels = Weechat.get_channel_info(Weechat.get_info("server")) +if channels != nil + if channels == {} + Weechat.print("no channel") + else + channels.each do |n, c| + c.each do |key, value| + Weechat.print("#{n} -> #{key} = '#{value}'") + end + end + end +else + Weechat.print("error while getting channels") +end + +-- lua +chans = weechat.get_channel_info(weechat.get_info("server")) +if chans ~= nil then + if chans then + chan, chaninfos = next (chans, nil) + while (chan) do + key, value = next (chaninfos, nil) + while (key) do + weechat.print(chan.." -> "..key.." = '"..value.."'") + key, value = next (chaninfos, key) + end + chan, chaninfos = next (chans, chan) + end + else + weechat.print("no channel") + end +else + weechat.print("error while getting channels") +end + + +
+ +
+ get_nick_info + + + Perl prototype: + + weechat::get_nick_info(server, channel); + + + + Python prototype: + + weechat.get_nick_info(server, channel) + + + + Ruby prototype: + + Weechat.get_nick_info(server, channel) + + + + Lua prototype: + + weechat.get_nick_info(server, channel) + + + + Return list of nicks for a channel. + + + Return value: list of nicks on channel + (see ). + + + Examples: + +# perl +my $nicks = weechat::get_nick_info("freenode", "#weechat"); +if ($nicks) +{ + while (my ($nickname, $nickinfos) = each %$nicks) + { + while ( my ($key, $value) = each %$nickinfos) + { + weechat::print("$nickname -> $key = '$value'"); + } + } +} +else +{ + weechat::print("no nick"); +} + +# python +nicks = weechat.get_nick_info("freenode", "#weechat") +if nicks != None: + if nicks == {}: + weechat.prnt("no nick") + else: + for n in nicks: + for f in nicks[n]: + weechat.prnt("%s -> %s = '%s'" % (n, f, str(nicks[n][f]))) +else: + weechat.prnt("error while getting nicks") + +# ruby +nicks = Weechat.get_nick_info("freenode", "#weechat") +if nicks != nil + if nicks == {} + Weechat.print("no nick") + else + nicks.each do |nk, nattr| + nattr.each do |key, value| + Weechat.print("#{nk} -> #{key} = '#{value}'") + end + end + end +else + Weechat.print("error while getting nicks") +end + +-- lua +nicks = weechat.get_nick_info("freenode", "#weechat") +if nicks ~= nil then + if nicks then + nick, nickinfos = next (nicks, nil) + while (nick) do + key, value = next (nickinfos, nil) + while (key) do + weechat.print(nick.." -> "..key.." = '"..value.."'") + key, value = next (nickinfos, key) + end + nick, nickinfos = next (nicks, nick) + end + else + weechat.print("no nick") + end +else + weechat.print("error while getting nicks") +end + + +
+ +
+ get_config + + + Perl prototype: + + weechat::get_config(option); + + + + Python prototype: + + weechat.get_config(option) + + + + Ruby prototype: + + Weechat.get_config(option) + + + + Lua prototype: + + weechat.get_config(option) + + + + Return value of a WeeChat config option. + + + Arguments: + + + + : name of option to read + + + + + + Return value: option value, empty string if not found. + + + Examples: + +# perl +$value1 = weechat::get_config("look_nicklist"); +$value2 = weechat::get_config("freenode.server_autojoin"); + +# python +value1 = weechat.get_config("look_nicklist") +value2 = weechat.get_config("freenode.server_autojoin") + +# ruby +value1 = Weechat.get_config("look_nicklist") +value2 = Weechat.get_config("freenode.server_autojoin") + +-- lua +value1 = weechat.get_config("look_nicklist") +value2 = weechat.get_config("freenode.server_autojoin") + + +
+ +
+ set_config + + + Perl prototype: + + weechat::set_config(option, value); + + + + Python prototype: + + weechat.set_config(option, value) + + + + Ruby prototype: + + Weechat.set_config(option, value) + + + + Lua prototype: + + weechat.set_config(option, value) + + + + Update value of a WeeChat config option. + + + Arguments: + + + + : name of option to update + + + + + : new value for option + + + + + + Return value: 1 if option was successfully updated, 0 if an error + occurred. + + + Examples: + +# perl +weechat::set_config("look_nicklist", "off"); +weechat::set_config("freenode.server_autojoin", "#weechat"); + +# python +weechat.set_config("look_nicklist", "off") +weechat.set_config("freenode.server_autojoin", "#weechat") + +# ruby +Weechat.set_config("look_nicklist", "off") +Weechat.set_config("freenode.server_autojoin", "#weechat") + +-- lua +weechat.set_config("look_nicklist", "off") +weechat.set_config("freenode.server_autojoin", "#weechat") + + +
+ +
+ get_plugin_config + + + Perl prototype: + + weechat::get_plugin_config(option); + + + + Python prototype: + + weechat.get_plugin_config(option) + + + + Ruby prototype: + + Weechat.get_plugin_config(option) + + + + Lua prototype: + + weechat.get_plugin_config(option) + + + + Return value of a plugin option. Option is read from file + "~/.weechat/plugins.rc" and is like: + "plugin.option=value" (note: plugin name + is automatically added). + + + Arguments: + + + + : name of option to read + + + + + + Return value: value of option, empty string if not found. + + + Examples : + +# perl +$value = weechat::get_plugin_config("my_var"); + +# python +value = weechat.get_plugin_config("my_var") + +# ruby +value = Weechat.get_plugin_config("my_var") + +-- lua +value = weechat.get_plugin_config("my_var") + + +
+ +
+ set_plugin_config + + + Perl prototype: + + weechat::set_plugin_config(option, value); + + + + Python prototype: + + weechat.set_plugin_config(option, value) + + + + Ruby prototype: + + Weechat.set_plugin_config(option, value) + + + + Lua prototype: + + weechat.set_plugin_config(option, value) + + + + Update value of a plugin option. Option is written in file + "~/.weechat/plugins.rc" and is like: + "plugin.option=value" (note: plugin name + is automatically added). + + + Arguments: + + + + : name of option to update + + + + + : new value for option + + + + + + Return value: 1 if option was successfully updated, 0 if an error + occurred. + + + Examples: + +# perl +weechat::set_plugin_config("my_var", "value"); + +# python +weechat.set_plugin_config("my_var", "value") + +# ruby +Weechat.set_plugin_config("my_var", "value") + +-- lua +weechat.set_plugin_config("my_var", "value") + + +
+ +
+ get_irc_color + + + Perl prototype: + + weechat::get_irc_color(color); + + + + Python prototype: + + weechat.get_irc_color(color) + + + + Ruby prototype: + + Weechat.get_irc_color(color) + + + + Lua prototype: + + weechat.get_irc_color(color) + + + + Return IRC color index with name. + + + Return value: IRC color index, -1 if color is not found + (see ). + + + Examples: + +# perl +my $color_blue = weechat::get_irc_color("blue"); + +# python +color_blue = weechat.get_irc_color("blue") + +# ruby +color_blue = Weechat.get_irc_color("blue") + +-- lua +color_blue = weechat.get_irc_color("blue") + + +
+ +
+ input_color + + + Perl prototype: + + weechat::input_color(color); + + + + Python prototype: + + weechat.input_color(color) + + + + Ruby prototype: + + Weechat.input_color(color) + + + + Lua prototype: + + weechat.input_color(color) + + + + Add color in input buffer. + + + Return value: none. + + + Examples: + +# perl +weechat::input_color(weechat::get_irc_color("blue"), 10, 5); + +# python +weechat.input_color(weechat.get_irc_color("blue"), 10, 5) + +# ruby +Weechat.input_color(Weechat.get_irc_color("blue"), 10, 5) + +-- lua +weechat.input_color(weechat.get_irc_color("blue"), 10, 5) + + +
+ +
+ get_window_info + + + Perl prototype: + + weechat::get_window_info(); + + + + Python prototype: + + weechat.get_window_info() + + + + Ruby prototype: + + Weechat.get_window_info() + + + + Lua prototype: + + weechat.get_window_info() + + + + Return list of WeeChat windows. + + + Return value: list of WeeChat windows + (see ). + + + Examples: + +# perl +my @wf = weechat::get_window_info(); +if (@wf) +{ + weechat::print("**** windows infos ****"); + foreach my $w (@wf) + { + while ( my ($key, $value) = each %$w) + { + weechat::print(" > $key => $value"); + } + weechat::print("----------------------"); + } +} +else +{ + weechat::print("**** no window info ****"); +} + +# python +wf = weechat.get_window_info() +if wf != None and wf != []: + weechat.prnt ("**** windows infos ****") + for w in wf: + for i in w: + weechat.prnt (" > %s => %s" % (i, w[i])) + weechat.prnt ("----------------------") +else: + weechat.prnt ("**** no window info ****") + +# ruby +wf = Weechat.get_window_info() +if wf != nil and wf != [] + Weechat.print("**** windows infos ****") + wf.each do |w| + w.each do |key, value| + Weechat.print(" > #{key} => #{value}") + end + Weechat.print("----------------------") + end +else + Weechat.print("**** no window info ****") +end + +-- lua +wf = weechat.get_window_info() +if wf then + weechat.print ("**** windows infos ****") + w, winfos = next (wf, nil) + while (w) do + key, value = next (winfos, nil) + while (key) do + weechat.print(" > " .. key .. " => " .. value) + key, value = next (winfos, key) + end + weechat.print ("----------------------") + w, winfos = next (wf, w) + end +else + weechat.print("**** no window info ****") +end + + +
+ +
+ get_buffer_info + + + Perl prototype: + + weechat::get_buffer_info(); + + + + Python prototype: + + weechat.get_buffer_info() + + + + Ruby prototype: + + Weechat.get_buffer_info() + + + + Lua prototype: + + weechat.get_buffer_info() + + + + Return list of WeeChat buffers. + + + Return value: list of WeeChat buffers + (see ). + + + Examples: + +# perl +my $bf = weechat::get_buffer_info(); +if ($bf) +{ + while ( my ($nobuf, $binfos) = each %$bf) + { + while ( my ($key, $value) = each %$binfos) + { + weechat::print(" > $key => $value"); + } + weechat::print("----------------------"); + } +} +else +{ + weechat::print("**** no buffer info ****"); +} + +# python +bf = weechat.get_buffer_info() +if bf != None and bf != {}: + for b in bf: + weechat.prnt ("**** info for buffer no %d ****" % b) + for c in bf[b]: + weechat.prnt (" > %s => %s" % (c, bf[b][c])) + weechat.prnt ("----------------------") +else: + weechat.prnt ("**** no buffer info ****") + +# ruby +bf = Weechat.get_buffer_info() +if bf != nil and bf != {} + bf.each do |n, c| + Weechat.print("**** info for buffer no #{n} ****") + c.each do |key, value| + Weechat.print(" > #{key} => #{value}") + end + Weechat.print("----------------------") + end +else + Weechat.print("**** no buffer info ****") +end + +-- lua +bf = weechat.get_buffer_info() +if bf then + b, binfos = next (bf, nil) + while (b) do + weechat.print("**** info for buffer no " .. b .. " ****") + key, value = next (binfos, nil) + while (key) do + weechat.print(" > " .. key .. " => " .. value) + key, value = next (binfos, key) + end + weechat.print ("----------------------") + b, infos = next (bf, b) + end +else + weechat.print("**** no buffer info ****") +end + + +
+ +
+ get_buffer_data + + + Perl prototype: + + weechat::get_buffer_data(server, channel); + + + + Python prototype: + + weechat.get_buffer_data(server, channel) + + + + Ruby prototype: + + Weechat.get_buffer_data(server, channel) + + + + Lua prototype: + + weechat.get_buffer_data(server, channel) + + + + Return content of buffer. + + + Return value: list of lines for buffer + (see ). + + + Examples: + +# perl +my $server = weechat::get_info("server"); +my $channel = weechat::get_info("channel"); +my @bc = weechat::get_buffer_data($server, $channel); +if (@bc) +{ + weechat::print("**** buffer data for '$channel'\@'$server' ****"); + foreach my $l (@bc) { + while ( my ($key, $value) = each %$l) { + weechat::print(" > $key => $value"); + } + weechat::print("----------------------"); + } +} +else +{ + weechat::print("**** no buffer data ****"); +} + +# python +server = weechat.get_info("server") +channel = weechat.get_info("channel") +bc = weechat.get_buffer_data(server, channel) +if bc != None and bc != []: + weechat.prnt ("**** buffer data for '%s'@'%s' ****" % (channel, server)) + for l in bc: + for i in l: + weechat.prnt (" > %s => %s" % (i, l[i])) + weechat.prnt ("----------------------") +else: + weechat.prnt ("**** no buffer data ****") + +# ruby +server = Weechat.get_info("server") +channel = Weechat.get_info("channel") +bc = Weechat.get_buffer_data(server, channel) +if bc != nil and bc != [] + Weechat.print("**** buffer data for '#{channel}'@'#{server}' ****") + bc.each do |l| + l.each do |key, value| + Weechat.print(" > #{key} => #{value}") + end + Weechat.print("----------------------") + end +else + Weechat.print("**** no buffer data ****") +end + +-- lua +server = weechat.get_info("server") +channel = weechat.get_info("channel") +bc = weechat.get_buffer_data(server, channel) +if bc then + b, bdatas = next (bc, nil) + weechat.print("**** buffer data for '" .. channel .. "'@'" .. server .. "' ****") + while (b) do + key, value = next (bdatas, nil) + while (key) do + weechat.print(" > " .. key .. " => " .. value) + key, value = next (bdatas, key) + end + weechat.print ("----------------------") + b, bdatas = next (bc, b) + end +else + weechat.print("**** no buffer data ****") +end + + +
+ +
+ +
diff --git a/doc/en/dev/plugins.en.xml b/doc/en/dev/plugins.en.xml new file mode 100644 index 000000000..fd2e2f7db --- /dev/null +++ b/doc/en/dev/plugins.en.xml @@ -0,0 +1,250 @@ + + + + + + Plugins + + + This chapter describes WeeChat plugin API and default plugins provided with + WeeChat. + + +
+ Plugins in WeeChat + + + A plugin is a C program which can call WeeChat functions defined in + an interface. + + + + This C program does not need WeeChat sources to compile and can be + dynamically loaded into WeeChat with command + /plugin. + + + + The plugin has to be a dynamic library, for dynamic loading by + operating system. + Under GNU/Linux, the file has ".so" extension, ".dll" under + Windows. + + +
+ +
+ Write a plugin + + + The plugin has to include "weechat-plugin.h" file (available in + WeeChat source code). + This file defines structures and types used to communicate with + WeeChat. + + + + The plugin must use some mandatory macros (to define some variables) + and some functions (without them the plugin can't load): + + + + + + Macro + Description + + + + + WEECHAT_PLUGIN_NAME + plugin name + + + WEECHAT_PLUGIN_DESCRIPTION + short description of plugin + + + WEECHAT_PLUGIN_VERSION + plugin version + + + WEECHAT_PLUGIN_WEECHAT_VERSION + + target WeeChat version where plugin will run (warning: plugin + will not run on any other WeeChat version!) + + + + WEECHAT_PLUGIN_LICENSE + plugin license + + + + + + + + + + Function + Description + + + + + int weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[]) + + function called when plugin is loaded, must return + WEECHAT_RC_OK if successful, WEECHAT_RC_ERROR if error + (if error, plugin will NOT be loaded), argc/argv are arguments + for plugin (given on command line by user) + + + + int weechat_plugin_end (struct t_weechat_plugin *plugin) + function called when plugin is unloaded + + + + + + + &plugin_api.en.xml; + +
+ Compile plugin + + + Compile does not need WeeChat sources, only file + "weechat-plugin.h". + + + + To compile a plugin which has one file "toto.c" (under GNU/Linux): + +$ gcc -fPIC -Wall -c toto.c +$ gcc -shared -fPIC -o libtoto.so toto.o + + + +
+ +
+ Load plugin into WeeChat + + + Copy "libtoto.so" file into system plugins directory (for example + "/usr/local/lib/weechat/plugins") or into + user's plugins directory (for example + "/home/xxxxx/.weechat/plugins"). + + + + Under WeeChat: + /plugin load toto + + +
+ +
+ Plugin example + + + Full example of plugin, which adds a /double command, which displays + two times arguments on current buffer, or execute two times a command + (ok that's not very useful, but that's just an example!): + +#include <stdlib.h> + +#include "weechat-plugin.h" + +WEECHAT_PLUGIN_NAME("double"); +WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat"); +WEECHAT_PLUGIN_AUTHOR("FlashCode <flashcode@flashtux.org>"); +WEECHAT_PLUGIN_VERSION("0.1"); +WEECHAT_PLUGIN_WEECHAT_VERSION("0.2.7"); +WEECHAT_PLUGIN_LICENSE("GPL3"); + +struct t_weechat_plugin *weechat_plugin = NULL; + + +/* "/double" command manager */ + +int +double_cmd (void *data, struct t_gui_buffer *buffer, int argc, + char **argv, char **argv_eol) +{ + /* make C compiler happy */ + (void) argv; + + if (argc > 1) + { + weechat_command (NULL, argv_eol[1]); + weechat_command (NULL, argv_eol[1]); + } + + return WEECHAT_RC_OK; +} + +int +weechat_plugin_init (struct t_weechat_plugin *plugin, + int argc, char *argv[]) +{ + weechat_plugin = plugin; + + weechat_hook_command ("double", + "Display two times a message", + "msg", + "msg: message to display two times", + NULL, + &double_cmd, NULL); + + return WEECHAT_RC_OK; +} + +int +weechat_plugin_end (struct t_weechat_plugin *plugin) +{ + /* nothing done here */ + (void) plugin; + + return WEECHAT_RC_OK; +} + + + +
+ +
+ + &plugin_irc.en.xml; + + + + &plugin_fifo.en.xml; + + + + &plugin_xfer.en.xml; + + diff --git a/doc/en/dev/weechat_dev.en.xml b/doc/en/dev/weechat_dev.en.xml new file mode 100644 index 000000000..e21d3cf0e --- /dev/null +++ b/doc/en/dev/weechat_dev.en.xml @@ -0,0 +1,101 @@ + + + + + + + + %include_autogen.xml; + + + + + + + +]> + + + + + + WeeChat 0.2.7-dev - Developer guide + Fast, light and extensible chat client + + + Sébastien + Helleu + flashcode AT flashtux.org + + + &date.xml; + + + 2008 + Sébastien Helleu + + + + + This manual is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <http://www.gnu.org/licenses/>. + + + + + + This manual documents development of WeeChat and its extensions. + It is part of WeeChat. + + + Latest version of this document can be found on this page: + + http://weechat.flashtux.org/doc.php + + + + + + + &intro.en.xml; + + + + &authors.en.xml; + + -- cgit v1.2.3