Mercurial Mercurial > mod-mcabber-lua / comparison
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs/api.mdwn
changeset 151 5d90caa7fb2c
parent 150 c8514af9b449
child 152 0cf6c938ac03
equal deleted inserted replaced
150:c8514af9b449 151:5d90caa7fb2c 
    34 
    34 
    35 <a name="yes.or.no.ansvers"></a>
 
    35 <a name="yes.or.no.ansvers"></a>
 
    36 ### yes or no ansvers  
    36 ### yes or no ansvers  
    37 **Values:**  1, 0, enable, disable, true, false, on, off, yes, no  
    37 **Values:**  1, 0, enable, disable, true, false, on, off, yes, no  
    38 
    38 
    39 <a name="main.yesno"></a>
 
    39 <a name="mcabber.yesno"></a>
 
    40 ### main.yesno
 
    40 ### mcabber.yesno
 
    41 According to [yes or no ansvers](#yes.or.no.ansvers) returns true or false.
 
    41 According to [yes or no ansvers](#yes.or.no.ansvers) returns true or false.
 
    42 If ansver is not recognized, returns nil.  
    42 If ansver is not recognized, returns nil.  
    43 **Arguments:** anything (string expected)    
    43 **Arguments:** anything (string expected)    
    44 **Return values:** boolean or nil  
    44 **Return values:** boolean or nil  
    45 
    45 
    46 <a name="main.version"></a>
 
    46 <a name="mcabber.version"></a>
 
    47 ### main.version
 
    47 ### mcabber.version
 
    48 Returns information about mcabber version  
    48 Returns table with information about mcabber  version  
    49 **Return values:** table  
    49 **Return values:** table  
    50 
    50 
    51 <a name="log.message.type"></a>
 
    51 <a name="log.message.type"></a>
 
    52 ### log message type  
    52 ### log message type  
    53 **Values:**  normal, log, debug, notutf8  
    53 **Values:**  normal, log, debug, notutf8  
    54 
    54 
    55 <a name="roster.type"></a>
 
    55 <a name="roster.type"></a>
 
    56 ### roster type  
    56 ### roster type  
    57 **Values:**  user, group, agent, room, special  
    57 **Values:**  user, group, agent, room, special  
    58 
    58 
    59 <a name="main.log"></a>
 
    59 <a name="mcabber.log"></a>
 
    60 ### main.log
 
    60 ### mcabber.log
 
    61 Prints message to log.
 
    61 Prints message to log.
 
    62 Note: most likely you need notutf8 flag enabled.  
    62 Note: most likely you need notutf8 flag enabled.  
    63 **Arguments:** [log message type](#log.message.type), message, message...  
    63 **Arguments:** [log message type](#log.message.type), message, message...  
    64 
    64 
    65 <a name="main.option"></a>
 
    65 <a name="mcabber.option"></a>
 
    66 ### main.option
 
    66 ### mcabber.option
 
    67 Sets or gets value of mcabber option.
 
    67 Sets or gets value of given config option.
 
    68 You can specify nil as a value to delete option.
 
    68 You can specify nil as a value to delete option.
 
    69 If you omit option name, it returns hash table of all options.  
    69 If you omit option name, it returns hash table of all options.  
    70 **Arguments:** string (option name, optional), string (value, optional)    
    70 **Arguments:** string (option name, optional), string (value, optional)    
    71 **Return values:** string (value, optional)  
    71 **Return values:** string (value, optional)  
    72 
    72 
    73 <a name="main.alias"></a>
 
    73 <a name="mcabber.alias"></a>
 
    74 ### main.alias
 
    74 ### mcabber.alias
 
    75 Sets or gets alias.
 
    75 Sets or gets alias.
 
    76 You can specify nil as a command to delete alias.
 
    76 You can specify nil as a command to delete alias.
 
    77 If you omit alias name, it will return hash table of all aliases.  
    77 If you omit alias name, it will return hash table of all aliases.  
    78 **Arguments:** string (alias name, optional), string (command, optional)    
    78 **Arguments:** string (alias name, optional), string (command, optional)    
    79 **Return values:** string (command, optional)  
    79 **Return values:** string (command, optional)  
    80 
    80 
    81 <a name="main.bind"></a>
 
    81 <a name="mcabber.bind"></a>
 
    82 ### main.bind
 
    82 ### mcabber.bind
 
    83 Sets or gets binding.
 
    83 Sets or gets binding.
 
    84 You can specify nil as a command to unbind key.
 
    84 You can specify nil as a command to unbind key.
 
    85 If you omit keycode, it will return hash table of all bindings.  
    85 If you omit keycode, it will return hash table of all bindings.  
    86 **Arguments:** string (keycode, optional), string (command, optional)    
    86 **Arguments:** string (keycode, optional), string (command, optional)    
    87 **Return values:** string (command, optional)  
    87 **Return values:** string (command, optional)  
    88 
    88 
    89 <a name="main.fileoption"></a>
 
    89 <a name="mcabber.fileoption"></a>
 
    90 ### main.fileoption
 
    90 ### mcabber.fileoption
 
    91 Gets option, expanding it as filename.  
    91 Gets option, expanding it as filename.  
    92 **Arguments:** string (option name)    
    92 **Arguments:** string (option name)    
    93 **Return values:** string (expanded option value) or nil  
    93 **Return values:** string (expanded option value) or nil  
    94 
    94 
    95 <a name="main.connection"></a>
 
    95 <a name="mcabber.connection"></a>
 
    96 ### main.connection
 
    96 ### mcabber.connection
 
    97 Returns lightuserdata of mcabber's loudmouth connection.
 
    97 Returns lightuserdata of mcabber's loudmouth connection.
 
    98 This can be very useful with lua-loudmouth, and not much otherwise.  
    98 This can be very useful with lua-loudmouth, and not much otherwise.  
    99 **Return values:** lightuserdata or nil  
    99 **Return values:** lightuserdata or nil  
   100 
   100 
   101 <a name="main.print.info"></a>
 
   101 <a name="mcabber.print.info"></a>
 
   102 ### main.print_info
 
   102 ### mcabber.print_info
 
   103 Prints a system message to buddy's window.  
   103 Prints a system message to buddy's window.  
   104 **Arguments:** string (jid), string (message)  
   104 **Arguments:** string (jid), string (message)  
   105 
   105 
   106 <a name="main.beep"></a>
 
   106 <a name="mcabber.beep"></a>
 
   107 ### main.beep
 
   107 ### mcabber.beep
 
   108 Beeps with system speaker.
 
   108 Beeps with system speaker.
 
   109 
   109 
   110 <a name="main.run"></a>
 
   110 <a name="mcabber.run"></a>
 
   111 ### main.run
 
   111 ### mcabber.run
 
   112 Runs specified mcabber command.  
   112 Executes given string as a mcabber  command.
 
       
   113 Note: You should omit '/' in the beginning.  
   113 **Arguments:** string  
   114 **Arguments:** string  
   114 
   115 
   115 <a name="main.status"></a>
 
   116 <a name="mcabber.status"></a>
 
   116 ### main.status
 
   117 ### mcabber.status
 
   117 Returns your current status.  
   118 Returns your current status.  
   118 **Return values:** string (status letter), string (status message)  
   119 **Return values:** string (status letter), string (status message)  
   119 
   120 
   120 <a name="main.roster"></a>
 
   121 <a name="mcabber.roster"></a>
 
   121 ### main.roster
 
   122 ### mcabber.roster
 
   122 Returns array of jids of buddies in roster.  
   123 Returns array of jids of buddies in roster.  
   123 **Return values:** table  
   124 **Return values:** table  
   124 
   125 
   125 <a name="main.current.buddy"></a>
 
   126 <a name="mcabber.current.buddy"></a>
 
   126 ### main.current_buddy
 
   127 ### mcabber.current_buddy
 
   127 Returns jid of current selected buddy or sets current buddy to buddy with specified jid.  
   128 Returns jid of current selected buddy or sets current buddy to buddy with specified jid.  
   128 **Arguments:** string (optional)    
   129 **Arguments:** string (optional)    
   129 **Return values:** string (optional)  
   130 **Return values:** string (optional)  
   130 
   131 
   131 <a name="main.full.jid"></a>
 
   132 <a name="mcabber.full.jid"></a>
 
   132 ### main.full_jid
 
   133 ### mcabber.full_jid
 
   133 Returns full jid (with current resource) of specified buddy (or current, if not specified).
 
   134 Returns full jid (with current resource) of specified buddy (or current, if not specified).
 
   134 Note, that if there are no resources online, it will return just what it got.  
   135 Note, that if there are no resources online, it will return just what it got.  
   135 **Arguments:** string (jid, optional)    
   136 **Arguments:** string (jid, optional)    
   136 **Return values:** string (jid)  
   137 **Return values:** string (jid)  
   137 
   138 
   138 <a name="resources.table"></a>
 
   139 <a name="resources.table"></a>
 
   139 ### resources table
 
   140 ### resources table
 
   140 Hash table with resource name as keys and another hash tables as values.
 
   141 Hash table with resource name as keys and another hash tables as values.
 
   141 Inner tables contain resource-specific information: priority, status and message.
 
   142 Inner tables contain resource-specific information: priority, status and message.
 
   142 
   143 
   143 <a name="main.buddy.info"></a>
 
   144 <a name="mcabber.buddy.info"></a>
 
   144 ### main.buddy_info
 
   145 ### mcabber.buddy_info
 
   145 Returns a hash table with information on specified buddy.
 
   146 Returns a hash table with information on specified buddy.
 
   146 Table contains fields type, name, onserver and resources (which points to [resources table](#resources.table)).  
   147 Table contains fields type, name, onserver and resources (which points to [resources table](#resources.table)).  
   147 **Arguments:** string (jid)    
   148 **Arguments:** string (jid)    
   148 **Return values:** table  
   149 **Return values:** table  
   149 
   150 
   150 <a name="main.add.feature"></a>
 
   151 <a name="mcabber.add.feature"></a>
 
   151 ### main.add_feature
 
   152 ### mcabber.add_feature
 
   152 Adds xmlns to disco#info features list.  
   153 Adds xmlns to disco#info features list.  
   153 **Arguments:** string (xmlns)  
   154 **Arguments:** string (xmlns)  
   154 
   155 
   155 <a name="main.del.feature"></a>
 
   156 <a name="mcabber.del.feature"></a>
 
   156 ### main.del_feature
 
   157 ### mcabber.del_feature
 
   157 Removes xmlns from disco#info features list.  
   158 Removes xmlns from disco#info features list.  
   158 **Arguments:** stirng (xmlns)  
   159 **Arguments:** stirng (xmlns)  
   159 
   160 
   160 <a name="event.context"></a>
 
   161 <a name="event.context"></a>
 
   161 ### event context
 
   162 ### event context
 
   166 ### event function
 
   167 ### event function
 
   167 Function to be called, when some event state change occurs  
   168 Function to be called, when some event state change occurs  
   168 **Arguments:** [event context](#event.context), string (event args)    
   169 **Arguments:** [event context](#event.context), string (event args)    
   169 **Return values:** boolean (if event shoud be preserved)  
   170 **Return values:** boolean (if event shoud be preserved)  
   170 
   171 
   171 <a name="main.event"></a>
 
   172 <a name="mcabber.event"></a>
 
   172 ### main.event
 
   173 ### mcabber.event
 
   173 Creates new event. If called without arguments, returns event id list.  
   174 Creates new event. If called without arguments, returns event id list.  
   174 **Arguments:** [event function](#event.function) (optional), string (event id), string (description, optional), integer (expiration timeout, optional)    
   175 **Arguments:** [event function](#event.function) (optional), string (event id), string (description, optional), integer (expiration timeout, optional)    
   175 **Return values:** string (event id) or nothing (creation error) or table (list of event names)  
   176 **Return values:** string (event id) or nothing (creation error) or table (list of event names)  
   176 
   177 
   177 <a name="completion.type"></a>
 
   178 <a name="completion.type"></a>
 
   207 ### command function
 
   208 ### command function
 
   208 Function to handle newly registered command.
 
   209 Function to handle newly registered command.
 
   209 Argument type passed depends on how command is registered.  
   210 Argument type passed depends on how command is registered.  
   210 **Arguments:** string (arguments) or [command arguments table](#command.arguments.table)  
   211 **Arguments:** string (arguments) or [command arguments table](#command.arguments.table)  
   211 
   212 
   212 <a name="main.parse.args"></a>
 
   213 <a name="mcabber.parse.args"></a>
 
   213 ### main.parse_args
 
   214 ### mcabber.parse_args
 
   214 Function to parse command argument string to [command arguments table](#command.arguments.table).  
   215 Function to parse command argument string to [command arguments table](#command.arguments.table).  
   215 **Arguments:** string    
   216 **Arguments:** string    
   216 **Return values:** table  
   217 **Return values:** table  
   217 
   218 
   218 <a name="main.add.category"></a>
 
   219 <a name="mcabber.add.category"></a>
 
   219 ### main.add_category
 
   220 ### mcabber.add_category
 
   220 Adds completion category.  
   221 Adds completion category.  
   221 **Arguments:** table (values are used as words for completion, optional), argument enum value ([completion sorting order](#completion.sorting.order), optional)    
   222 **Arguments:** table (values are used as words for completion, optional), argument enum value ([completion sorting order](#completion.sorting.order), optional)    
   222 **Return values:** integer (category id, in fact [completion type](#completion.type)) or nil  
   223 **Return values:** integer (category id, in fact [completion type](#completion.type)) or nil  
   223 
   224 
   224 <a name="main.del.category"></a>
 
   225 <a name="mcabber.del.category"></a>
 
   225 ### main.del_category
 
   226 ### mcabber.del_category
 
   226 Removes completion category.  
   227 Removes completion category.  
   227 **Arguments:** integer (category id)  
   228 **Arguments:** integer (category id)  
   228 
   229 
   229 <a name="main.add.completion"></a>
 
   230 <a name="mcabber.add.completion"></a>
 
   230 ### main.add_completion
 
   231 ### mcabber.add_completion
 
   231 Adds word to a completion list.  
   232 Adds word to a completion list.  
   232 **Arguments:** integer (completion group id), string (word)  
   233 **Arguments:** integer (completion group id), string (word)  
   233 
   234 
   234 <a name="main.del.completion"></a>
 
   235 <a name="mcabber.del.completion"></a>
 
   235 ### main.del_completion
 
   236 ### mcabber.del_completion
 
   236 Removes word from a completion list.  
   237 Removes word from a completion list.  
   237 **Arguments:** integer (completion group id), string (word)  
   238 **Arguments:** integer (completion group id), string (word)  
   238 
   239 
   239 <a name="main.command"></a>
 
   240 <a name="mcabber.command"></a>
 
   240 ### main.command
 
   241 ### mcabber.command
 
   241 Associates mcabber command name and lua function.
 
   242 Associates mcabber  command name with given lua function.
 
   242 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.
 
   243 As a completion you can also specify a string name (see [completion type](#completion.type)) instead of table.
 
       
   244 For third-party completions you can just pass integer id.
 
   243 Note, that for now there are no way to unregister completion group, so, resources can be exausted easily.
 
   245 Note, that for now there are no way to unregister completion group, so, resources can be exausted easily.
 
   244 Also note, that it ignores keys in a completion table.  
   246 Also note, that it ignores keys in a completion table.  
   245 **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)    
   247 **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)    
   246 **Return values:** userdata (command object)  
   248 **Return values:** userdata (command object)  
   247 
   249 
   252 <a name="timer.function"></a>
 
   254 <a name="timer.function"></a>
 
   253 ### timer function
 
   255 ### timer function
 
   254 Function, that will be called periodically until it returns false.  
   256 Function, that will be called periodically until it returns false.  
   255 **Return values:** boolean  
   257 **Return values:** boolean  
   256 
   258 
   257 <a name="main.timer"></a>
 
   259 <a name="mcabber.timer"></a>
 
   258 ### main.timer
 
   260 ### mcabber.timer
 
   259 Creates new [timer function](#timer.function), that will be called periodically.  
   261 Creates new [timer function](#timer.function), that will be called periodically.  
   260 **Arguments:** integer (interval, seconds), [timer function](#timer.function)  
   262 **Arguments:** integer (interval, seconds), [timer function](#timer.function)  
   261 
   263 
   262 <a name="background.reading.function"></a>
 
   264 <a name="background.reading.function"></a>
 
   263 ### background reading function
 
   265 ### background reading function
 
   264 Function, that processes output from pipe in asynchronous way.  
   266 Function, that processes output from pipe in asynchronous way.  
   265 **Arguments:** string (data) or nil (eof)    
   267 **Arguments:** string (data) or nil (eof)    
   266 **Return values:** boolean (false if reading should be terminated)  
   268 **Return values:** boolean (false if reading should be terminated)  
   267 
   269 
   268 <a name="main.bgread"></a>
 
   270 <a name="mcabber.bgread"></a>
 
   269 ### main.bgread
 
   271 ### mcabber.bgread
 
   270 Runs specified command and passes its output to a given function.  
   272 Runs specified command and passes its output to a given function.  
   271 **Arguments:** string (command), [background reading function](#background.reading.function)  
   273 **Arguments:** string (command), [background reading function](#background.reading.function)  
   272 
   274 
   273 <a name="hook.handler.result"></a>
 
   275 <a name="hook.handler.result"></a>
 
   274 ### hook handler result
 
   276 ### hook handler result
 
   285 Function to be called, when hook will be processsed.
 
   287 Function to be called, when hook will be processsed.
 
   286 XXX: we can provide object as argument, but is this necessary?  
   288 XXX: we can provide object as argument, but is this necessary?  
   287 **Arguments:** table (arguments hash)    
   289 **Arguments:** table (arguments hash)    
   288 **Return values:** [hook handler result](#hook.handler.result)  
   290 **Return values:** [hook handler result](#hook.handler.result)  
   289 
   291 
   290 <a name="main.hook.run"></a>
 
   292 <a name="mcabber.hook.run"></a>
 
   291 ### main.hook_run
 
   293 ### mcabber.hook_run
 
   292 Runs handlers for given hook with supplied arguments.  
   294 Runs handlers for given hook with supplied arguments.  
   293 **Arguments:** string (hook name), table (hook arguments)    
   295 **Arguments:** string (hook name), table (hook arguments)    
   294 **Return values:** [return enum field](#return.enum.field) ([hook handler result](#hook.handler.result))  
   296 **Return values:** [return enum field](#return.enum.field) ([hook handler result](#hook.handler.result))  
   295 
   297 
   296 <a name="main.hook"></a>
 
   298 <a name="mcabber.hook"></a>
 
   297 ### main.hook
 
   299 ### mcabber.hook
 
   298 Installs hook handler, returns an object, that you need to keep until
 
   300 Installs hook handler, returns an object, that you need to keep until
 
   299 hook handling is no more needed.  
   301 hook handling is no more needed.  
   300 **Arguments:** string (hook name), [hook function](#hook.function), integer (priority, optional)    
   302 **Arguments:** string (hook name), [hook function](#hook.function), integer (priority, optional)    
   301 **Return values:** userdata (hook object)  
   303 **Return values:** userdata (hook object)  
   302 
   304 
   305 Unregisters given hook handler from mcabber. Object will be destroyed later.
 
   307 Unregisters given hook handler from mcabber. Object will be destroyed later.
 
   306 
   308 
   307 <a name="guard.function"></a>
 
   309 <a name="guard.function"></a>
 
   308 ### guard function
 
   310 ### guard function
 
   309 Function to be called, when option changes it's value.
 
   311 Function to be called, when option changes it's value.
 
   310 Old option value is still accessible through [main.option](#main.option).  
   312 Old option value is still accessible through main.option.  
   311 **Arguments:** string (key), string (new value)    
   313 **Arguments:** string (key), string (new value)    
   312 **Return values:** string (value to save in hash table)  
   314 **Return values:** string (value to save in hash table)  
   313 
   315 
   314 <a name="main.add.guard"></a>
 
   316 <a name="mcabber.add.guard"></a>
 
   315 ### main.add_guard
 
   317 ### mcabber.add_guard
 
   316 Installs option guard for given option.  
   318 Installs option guard for given option.  
   317 **Arguments:** string ( option name ), [guard function](#guard.function)    
   319 **Arguments:** string ( option name ), [guard function](#guard.function)    
   318 **Return values:** boolean ( success )  
   320 **Return values:** boolean ( success )  
   319 
   321 
   320 <a name="main.del.guard"></a>
 
   322 <a name="mcabber.del.guard"></a>
 
   321 ### main.del_guard
 
   323 ### mcabber.del_guard
 
   322 Removes option guard from given option.
 
   324 Removes option guard from given option.
 
   323 By default, lua will refuse to remove guards, not installed
 
   325 By default, lua will refuse to remove guards, not installed
 
   324 by lua. Still, you can force guard removal.  
   326 by lua. Still, you can force guard removal.  
   325 **Arguments:** string ( option name ), boolean ( force removal )    
   327 **Arguments:** string ( option name ), boolean ( force removal )    
   326 **Return values:** boolean ( success )  
   328 **Return values:** boolean ( success )
mod-mcabber-lua