# HG changeset patch
# User Myhailo Danylenko <isbear@ukrpost.net>
# Date 1458249420 -7200
# Node ID 5d90caa7fb2cef5c1cc091237e9f58570d9d642f
# Parent  c8514af9b449c623875d971612b172f0d17669a0
Switch global name from 'main' to 'mcabber' (v0.0.5)

diff -r c8514af9b449 -r 5d90caa7fb2c CMakeLists.txt
--- a/CMakeLists.txt	Sat Mar 05 18:36:28 2016 +0200
+++ b/CMakeLists.txt	Thu Mar 17 23:17:00 2016 +0200
@@ -16,13 +16,14 @@
 
 cmake_minimum_required(VERSION 2.6)
 project(lua C)
-set(PROJECT_VERSION "0.0.4")
+set(PROJECT_VERSION "0.0.5")
 
 ## User options
 option(DEBUG                 "Enable debugging output"                                                           ON)
 option(ENABLE_LUA_ALIAS      "Enable aliasing command '/lua' to corresponding '/lua5.x' at module loading time"  ON)
 option(LLM_CONNECTION_ENABLE "Enable exposing of mcabber loudmouth connection to lua"                            ON)
 option(LLM_LOG_HANDLER       "Enable registration of log messages handler for lua-loudmouth library's messages"  ON)
+option(COMPAT_0_0_4          "Provide global 'main' as alias to 'mcabber' for compatibility with v0.0.4"         ON)
 set(ML_SOURCE_PRIORITY G_PRIORITY_HIGH_IDLE CACHE STRING "Glib event source priority for timeout and bgread")
 set(ML_BGREAD_BUFFER   4096                 CACHE STRING "Background pipe reading buffer size")
 set(OPT_MLUA_RC        "lua_init_filename"  CACHE STRING "Mcabber option name to specify lua initialization file")
diff -r c8514af9b449 -r 5d90caa7fb2c config.h.in
--- a/config.h.in	Sat Mar 05 18:36:28 2016 +0200
+++ b/config.h.in	Thu Mar 17 23:17:00 2016 +0200
@@ -24,6 +24,9 @@
 // define this to enable debugging output
 #cmakedefine DEBUG
 
+// define this to enable compatibility with v0.0.4
+#cmakedefine COMPAT_0_0_4
+
 // define this if you want lua to create alias to '/lua' at module loading
 #cmakedefine ENABLE_LUA_ALIAS
 
diff -r c8514af9b449 -r 5d90caa7fb2c docs/api.mdwn
--- a/docs/api.mdwn	Sat Mar 05 18:36:28 2016 +0200
+++ b/docs/api.mdwn	Thu Mar 17 23:17:00 2016 +0200
@@ -36,16 +36,16 @@
 ### yes or no ansvers  
 **Values:**  1, 0, enable, disable, true, false, on, off, yes, no  
 
-<a name="main.yesno"></a>
-### main.yesno
+<a name="mcabber.yesno"></a>
+### mcabber.yesno
 According to [yes or no ansvers](#yes.or.no.ansvers) returns true or false.
 If ansver is not recognized, returns nil.  
 **Arguments:** anything (string expected)    
 **Return values:** boolean or nil  
 
-<a name="main.version"></a>
-### main.version
-Returns information about mcabber version  
+<a name="mcabber.version"></a>
+### mcabber.version
+Returns table with information about mcabber  version  
 **Return values:** table  
 
 <a name="log.message.type"></a>
@@ -56,80 +56,81 @@
 ### roster type  
 **Values:**  user, group, agent, room, special  
 
-<a name="main.log"></a>
-### main.log
+<a name="mcabber.log"></a>
+### mcabber.log
 Prints message to log.
 Note: most likely you need notutf8 flag enabled.  
 **Arguments:** [log message type](#log.message.type), message, message...  
 
-<a name="main.option"></a>
-### main.option
-Sets or gets value of mcabber option.
+<a name="mcabber.option"></a>
+### mcabber.option
+Sets or gets value of given config option.
 You can specify nil as a value to delete option.
 If you omit option name, it returns hash table of all options.  
 **Arguments:** string (option name, optional), string (value, optional)    
 **Return values:** string (value, optional)  
 
-<a name="main.alias"></a>
-### main.alias
+<a name="mcabber.alias"></a>
+### mcabber.alias
 Sets or gets alias.
 You can specify nil as a command to delete alias.
 If you omit alias name, it will return hash table of all aliases.  
 **Arguments:** string (alias name, optional), string (command, optional)    
 **Return values:** string (command, optional)  
 
-<a name="main.bind"></a>
-### main.bind
+<a name="mcabber.bind"></a>
+### mcabber.bind
 Sets or gets binding.
 You can specify nil as a command to unbind key.
 If you omit keycode, it will return hash table of all bindings.  
 **Arguments:** string (keycode, optional), string (command, optional)    
 **Return values:** string (command, optional)  
 
-<a name="main.fileoption"></a>
-### main.fileoption
+<a name="mcabber.fileoption"></a>
+### mcabber.fileoption
 Gets option, expanding it as filename.  
 **Arguments:** string (option name)    
 **Return values:** string (expanded option value) or nil  
 
-<a name="main.connection"></a>
-### main.connection
+<a name="mcabber.connection"></a>
+### mcabber.connection
 Returns lightuserdata of mcabber's loudmouth connection.
 This can be very useful with lua-loudmouth, and not much otherwise.  
 **Return values:** lightuserdata or nil  
 
-<a name="main.print.info"></a>
-### main.print_info
+<a name="mcabber.print.info"></a>
+### mcabber.print_info
 Prints a system message to buddy's window.  
 **Arguments:** string (jid), string (message)  
 
-<a name="main.beep"></a>
-### main.beep
+<a name="mcabber.beep"></a>
+### mcabber.beep
 Beeps with system speaker.
 
-<a name="main.run"></a>
-### main.run
-Runs specified mcabber command.  
+<a name="mcabber.run"></a>
+### mcabber.run
+Executes given string as a mcabber  command.
+Note: You should omit '/' in the beginning.  
 **Arguments:** string  
 
-<a name="main.status"></a>
-### main.status
+<a name="mcabber.status"></a>
+### mcabber.status
 Returns your current status.  
 **Return values:** string (status letter), string (status message)  
 
-<a name="main.roster"></a>
-### main.roster
+<a name="mcabber.roster"></a>
+### mcabber.roster
 Returns array of jids of buddies in roster.  
 **Return values:** table  
 
-<a name="main.current.buddy"></a>
-### main.current_buddy
+<a name="mcabber.current.buddy"></a>
+### mcabber.current_buddy
 Returns jid of current selected buddy or sets current buddy to buddy with specified jid.  
 **Arguments:** string (optional)    
 **Return values:** string (optional)  
 
-<a name="main.full.jid"></a>
-### main.full_jid
+<a name="mcabber.full.jid"></a>
+### mcabber.full_jid
 Returns full jid (with current resource) of specified buddy (or current, if not specified).
 Note, that if there are no resources online, it will return just what it got.  
 **Arguments:** string (jid, optional)    
@@ -140,20 +141,20 @@
 Hash table with resource name as keys and another hash tables as values.
 Inner tables contain resource-specific information: priority, status and message.
 
-<a name="main.buddy.info"></a>
-### main.buddy_info
+<a name="mcabber.buddy.info"></a>
+### mcabber.buddy_info
 Returns a hash table with information on specified buddy.
 Table contains fields type, name, onserver and resources (which points to [resources table](#resources.table)).  
 **Arguments:** string (jid)    
 **Return values:** table  
 
-<a name="main.add.feature"></a>
-### main.add_feature
+<a name="mcabber.add.feature"></a>
+### mcabber.add_feature
 Adds xmlns to disco#info features list.  
 **Arguments:** string (xmlns)  
 
-<a name="main.del.feature"></a>
-### main.del_feature
+<a name="mcabber.del.feature"></a>
+### mcabber.del_feature
 Removes xmlns from disco#info features list.  
 **Arguments:** stirng (xmlns)  
 
@@ -168,8 +169,8 @@
 **Arguments:** [event context](#event.context), string (event args)    
 **Return values:** boolean (if event shoud be preserved)  
 
-<a name="main.event"></a>
-### main.event
+<a name="mcabber.event"></a>
+### mcabber.event
 Creates new event. If called without arguments, returns event id list.  
 **Arguments:** [event function](#event.function) (optional), string (event id), string (description, optional), integer (expiration timeout, optional)    
 **Return values:** string (event id) or nothing (creation error) or table (list of event names)  
@@ -209,37 +210,38 @@
 Argument type passed depends on how command is registered.  
 **Arguments:** string (arguments) or [command arguments table](#command.arguments.table)  
 
-<a name="main.parse.args"></a>
-### main.parse_args
+<a name="mcabber.parse.args"></a>
+### mcabber.parse_args
 Function to parse command argument string to [command arguments table](#command.arguments.table).  
 **Arguments:** string    
 **Return values:** table  
 
-<a name="main.add.category"></a>
-### main.add_category
+<a name="mcabber.add.category"></a>
+### mcabber.add_category
 Adds completion category.  
 **Arguments:** table (values are used as words for completion, optional), argument enum value ([completion sorting order](#completion.sorting.order), optional)    
 **Return values:** integer (category id, in fact [completion type](#completion.type)) or nil  
 
-<a name="main.del.category"></a>
-### main.del_category
+<a name="mcabber.del.category"></a>
+### mcabber.del_category
 Removes completion category.  
 **Arguments:** integer (category id)  
 
-<a name="main.add.completion"></a>
-### main.add_completion
+<a name="mcabber.add.completion"></a>
+### mcabber.add_completion
 Adds word to a completion list.  
 **Arguments:** integer (completion group id), string (word)  
 
-<a name="main.del.completion"></a>
-### main.del_completion
+<a name="mcabber.del.completion"></a>
+### mcabber.del_completion
 Removes word from a completion list.  
 **Arguments:** integer (completion group id), string (word)  
 
-<a name="main.command"></a>
-### main.command
-Associates mcabber command name and lua function.
-As a completion you can also specify a string name (see [completion type](#completion.type)) instead of table, for non-builtin, you can just pass integer id.
+<a name="mcabber.command"></a>
+### mcabber.command
+Associates mcabber  command name with given lua function.
+As a completion you can also specify a string name (see [completion type](#completion.type)) instead of table.
+For third-party completions you can just pass integer id.
 Note, that for now there are no way to unregister completion group, so, resources can be exausted easily.
 Also note, that it ignores keys in a completion table.  
 **Arguments:** string (command name), [command function](#command.function), boolean (parse args flag, optional), table (completions, optional)/[completion type](#completion.type) (or integer comletion group id, optional)    
@@ -254,8 +256,8 @@
 Function, that will be called periodically until it returns false.  
 **Return values:** boolean  
 
-<a name="main.timer"></a>
-### main.timer
+<a name="mcabber.timer"></a>
+### mcabber.timer
 Creates new [timer function](#timer.function), that will be called periodically.  
 **Arguments:** integer (interval, seconds), [timer function](#timer.function)  
 
@@ -265,8 +267,8 @@
 **Arguments:** string (data) or nil (eof)    
 **Return values:** boolean (false if reading should be terminated)  
 
-<a name="main.bgread"></a>
-### main.bgread
+<a name="mcabber.bgread"></a>
+### mcabber.bgread
 Runs specified command and passes its output to a given function.  
 **Arguments:** string (command), [background reading function](#background.reading.function)  
 
@@ -287,14 +289,14 @@
 **Arguments:** table (arguments hash)    
 **Return values:** [hook handler result](#hook.handler.result)  
 
-<a name="main.hook.run"></a>
-### main.hook_run
+<a name="mcabber.hook.run"></a>
+### mcabber.hook_run
 Runs handlers for given hook with supplied arguments.  
 **Arguments:** string (hook name), table (hook arguments)    
 **Return values:** [return enum field](#return.enum.field) ([hook handler result](#hook.handler.result))  
 
-<a name="main.hook"></a>
-### main.hook
+<a name="mcabber.hook"></a>
+### mcabber.hook
 Installs hook handler, returns an object, that you need to keep until
 hook handling is no more needed.  
 **Arguments:** string (hook name), [hook function](#hook.function), integer (priority, optional)    
@@ -307,18 +309,18 @@
 <a name="guard.function"></a>
 ### guard function
 Function to be called, when option changes it's value.
-Old option value is still accessible through [main.option](#main.option).  
+Old option value is still accessible through main.option.  
 **Arguments:** string (key), string (new value)    
 **Return values:** string (value to save in hash table)  
 
-<a name="main.add.guard"></a>
-### main.add_guard
+<a name="mcabber.add.guard"></a>
+### mcabber.add_guard
 Installs option guard for given option.  
 **Arguments:** string ( option name ), [guard function](#guard.function)    
 **Return values:** boolean ( success )  
 
-<a name="main.del.guard"></a>
-### main.del_guard
+<a name="mcabber.del.guard"></a>
+### mcabber.del_guard
 Removes option guard from given option.
 By default, lua will refuse to remove guards, not installed
 by lua. Still, you can force guard removal.  
diff -r c8514af9b449 -r 5d90caa7fb2c lua.c
--- a/lua.c	Sat Mar 05 18:36:28 2016 +0200
+++ b/lua.c	Thu Mar 17 23:17:00 2016 +0200
@@ -196,7 +196,7 @@
 	{ NULL,     -1 },
 };
 
-/// main.yesno
+/// mcabber.yesno
 /// According to yes or no ansvers returns true or false.
 /// If ansver is not recognized, returns nil.
 /// A: anything (string expected)
@@ -217,8 +217,8 @@
 	return 1;
 }
 
-/// main.version
-/// Returns information about mcabber version
+/// mcabber.version
+/// Returns table with information about mcabber  version
 /// R: table
 static int lua_main_version (lua_State *L)
 {
@@ -263,7 +263,7 @@
 	{ NULL,      0                   },
 };
 
-/// main.log
+/// mcabber.log
 /// Prints message to log.
 /// Note: most likely you need notutf8 flag enabled.
 /// A: log message type, message, message...
@@ -287,8 +287,8 @@
 	lua_settable (L, -3);
 }
 
-/// main.option
-/// Sets or gets value of mcabber option.
+/// mcabber.option
+/// Sets or gets value of given mcabber config option.
 /// You can specify nil as a value to delete option.
 /// If you omit option name, it returns hash table of all options.
 /// A: string (option name, optional), string (value, optional)
@@ -325,7 +325,7 @@
 	}
 }
 
-/// main.alias
+/// mcabber.alias
 /// Sets or gets alias.
 /// You can specify nil as a command to delete alias.
 /// If you omit alias name, it will return hash table of all aliases.
@@ -366,7 +366,7 @@
 	}
 }
 
-/// main.bind
+/// mcabber.bind
 /// Sets or gets binding.
 /// You can specify nil as a command to unbind key.
 /// If you omit keycode, it will return hash table of all bindings.
@@ -405,7 +405,7 @@
 	}
 }
 
-/// main.fileoption
+/// mcabber.fileoption
 /// Gets option, expanding it as filename.
 /// A: string (option name)
 /// R: string (expanded option value) or nil
@@ -421,7 +421,7 @@
 }
 
 #ifdef LLM_CONNECTION_ENABLE
-/// main.connection
+/// mcabber.connection
 /// Returns lightuserdata of mcabber's loudmouth connection.
 /// This can be very useful with lua-loudmouth, and not much otherwise.
 /// R: lightuserdata or nil
@@ -435,7 +435,7 @@
 }
 #endif
 
-/// main.print_info
+/// mcabber.print_info
 /// Prints a system message to buddy's window.
 /// A: string (jid), string (message)
 static int lua_main_print_info (lua_State *L)
@@ -450,7 +450,7 @@
 	return 0;
 }
 
-/// main.beep
+/// mcabber.beep
 /// Beeps with system speaker.
 static int lua_main_beep (lua_State *L)
 {
@@ -458,8 +458,9 @@
 	return 0;
 }
 
-/// main.run
-/// Runs specified mcabber command.
+/// mcabber.run
+/// Executes given string as a mcabber  command.
+/// Note: You should omit '/' in the beginning.
 /// A: string
 static int lua_main_run (lua_State *L)
 {
@@ -467,7 +468,7 @@
 	return 0;
 }
 
-/// main.status
+/// mcabber.status
 /// Returns your current status.
 /// R: string (status letter), string (status message)
 static int lua_main_status (lua_State *L)
@@ -489,7 +490,7 @@
 	g_free (jid);
 }
 
-/// main.roster
+/// mcabber.roster
 /// Returns array of jids of buddies in roster.
 /// R: table
 static int lua_main_roster (lua_State *L)
@@ -499,7 +500,7 @@
 	return 1;
 }
 
-/// main.current_buddy
+/// mcabber.current_buddy
 /// Returns jid of current selected buddy or sets current buddy to buddy with specified jid.
 /// A: string (optional)
 /// R: string (optional)
@@ -520,7 +521,7 @@
 	}
 }
 
-/// main.full_jid
+/// mcabber.full_jid
 /// Returns full jid (with current resource) of specified buddy (or current, if not specified).
 /// Note, that if there are no resources online, it will return just what it got.
 /// A: string (jid, optional)
@@ -585,7 +586,7 @@
 	g_free (resource);
 }
 
-/// main.buddy_info
+/// mcabber.buddy_info
 /// Returns a hash table with information on specified buddy.
 /// Table contains fields type, name, onserver and resources (which points to resources table).
 /// A: string (jid)
@@ -633,7 +634,7 @@
 
 GSList *lua_added_features = NULL;
 
-/// main.add_feature
+/// mcabber.add_feature
 /// Adds xmlns to disco#info features list.
 /// A: string (xmlns)
 static int lua_main_add_feature (lua_State *L)
@@ -644,7 +645,7 @@
 	return 0;
 }
 
-/// main.del_feature
+/// mcabber.del_feature
 /// Removes xmlns from disco#info features list.
 /// A: stirng (xmlns)
 static int lua_main_del_feature (lua_State *L)
@@ -713,7 +714,7 @@
 	}
 }
 
-/// main.event
+/// mcabber.event
 /// Creates new event. If called without arguments, returns event id list.
 /// A: event function (optional), string (event id), string (description, optional), integer (expiration timeout, optional)
 /// R: string (event id) or nothing (creation error) or table (list of event names)
@@ -966,7 +967,7 @@
 	}
 }
 
-/// main.parse_args
+/// mcabber.parse_args
 /// Function to parse command argument string to command arguments table.
 /// A: string
 /// R: table
@@ -976,7 +977,7 @@
 	return 1;
 }
 
-/// main.add_category
+/// mcabber.add_category
 /// Adds completion category.
 /// A: table (values are used as words for completion, optional), argument enum value (completion sorting order, optional)
 /// R: integer (category id, in fact completion type) or nil
@@ -1013,7 +1014,7 @@
 	return 1;
 }
 
-/// main.del_category
+/// mcabber.del_category
 /// Removes completion category.
 /// A: integer (category id)
 static int lua_main_del_category (lua_State *L)
@@ -1024,7 +1025,7 @@
 	return 0;
 }
 
-/// main.add_completion
+/// mcabber.add_completion
 /// Adds word to a completion list.
 /// A: integer (completion group id), string (word)
 static int lua_main_add_completion (lua_State *L)
@@ -1036,7 +1037,7 @@
 	return 0;
 }
 
-/// main.del_completion
+/// mcabber.del_completion
 /// Removes word from a completion list.
 /// A: integer (completion group id), string (word)
 static int lua_main_del_completion (lua_State *L)
@@ -1048,9 +1049,10 @@
 	return 0;
 }
 
-/// main.command
-/// Associates mcabber command name and lua function.
-/// As a completion you can also specify a string name (see completion type) instead of table, for non-builtin, you can just pass integer id.
+/// mcabber.command
+/// Associates mcabber  command name with given lua function.
+/// As a completion you can also specify a string name (see completion type) instead of table.
+/// For third-party completions you can just pass integer id.
 /// Note, that for now there are no way to unregister completion group, so, resources can be exausted easily.
 /// Also note, that it ignores keys in a completion table.
 /// A: string (command name), command function, boolean (parse args flag, optional), table (completions, optional)/completion type (or integer comletion group id, optional)
@@ -1206,7 +1208,7 @@
 	return ret;
 }
 
-/// main.timer
+/// mcabber.timer
 /// Creates new timer function, that will be called periodically.
 /// A: integer (interval, seconds), timer function
 static int lua_main_timer (lua_State *L)
@@ -1292,7 +1294,7 @@
 	return ret;
 }
 
-/// main.bgread
+/// mcabber.bgread
 /// Runs specified command and passes its output to a given function.
 /// A: string (command), background reading function
 static int lua_main_bgread (lua_State *L)
@@ -1422,7 +1424,7 @@
 	return ret;
 }
 
-/// main.hook_run
+/// mcabber.hook_run
 /// Runs handlers for given hook with supplied arguments.
 /// A: string (hook name), table (hook arguments)
 /// R: return enum field (hook handler result)
@@ -1471,7 +1473,7 @@
 	return 1;
 }
 
-/// main.hook
+/// mcabber.hook
 /// Installs hook handler, returns an object, that you need to keep until
 /// hook handling is no more needed.
 /// A: string (hook name), hook function, integer (priority, optional)
@@ -1595,7 +1597,7 @@
 	}
 }
 
-/// main.add_guard
+/// mcabber.add_guard
 /// Installs option guard for given option.
 /// A: string ( option name ), guard function
 /// R: boolean ( success )
@@ -1616,7 +1618,7 @@
 	return 1;
 }
 
-/// main.del_guard
+/// mcabber.del_guard
 /// Removes option guard from given option.
 /// By default, lua will refuse to remove guards, not installed
 /// by lua. Still, you can force guard removal.
@@ -1779,7 +1781,11 @@
 
 	lua_newtable(lua);
 	luaL_setfuncs (lua, lua_reg_main, 0);
+#ifdef COMPAT_0_0_4
+	lua_pushvalue (lua, -1);
 	lua_setglobal (lua, "main");
+#endif
+	lua_setglobal (lua, "mcabber");
 	lua_register (lua, "dopath", lua_global_dopath);
 	lua_register (lua, "print",  lua_global_print );