This plugin is a would-be right hand of any conference administrator.

First of all, it is intended to help you banning nasty people
in all conferences where you have corresponding privileges.
Let them waste as least of your time as possible!

====================
####  COMMANDS  ####
====================

Usage:
---	To show short usage help of the plugin's commands:
/bldhelp

---	To ban in all rooms where you have admin privileges:
/bldjid JID
Some reason for banning (optional).

---	To ban a list of jids (separated with a space) in the current room:
/massban JID1 JID2 JID3 etc.
Some reason for banning (optional).

---	To unban a banned person in these rooms:
/unbldjid JID

---	If you're in a good mood (it's your birthday, for instance),
	you might want to unban all people banned in a certain room.
	To do so, just write there the following command:
/amnesty
and after a confirmation all outcasts from that room will be unbanned.
It is not recommended to use this command where you are not an owner.
	Sometimes you might just want to clean up your ban list without erasing it.
	For instance, if a bot banned a lot of atackers some time ago
	providing some reason, now you can use it to delete those most likely
	termporary jids from your ban list in order to be able to open it faster.
	Just specify a pattern that matches a required reason, for example:
/amnesty your nick is too long
	People (or bots) with reasons like "Your nick is TOO LONG!!!" will be unbanned.

	Please note that processing of too big ban lists (over more or less 700 entries)
	can provoke Stream Error (Policy Violation) and disconnection from server.
	The reason is the oversized resulting stanza which is being sent to the server.
	That's why a "valve" was added that shoots sending query when 700 entries are ready.
	That means that huge ban lists should be processed several times.

---	You can search for a certain word in the black list or in the member list
	of the current room using the following commands:
/inbanlist pattern
/inmemberlist pattern
	Ban reasons, if specified, will be shown in banlist search results.
	These searches are affected by the options(matching_rules), so for example
	if you want to know if some Jabber server is banned entirely just set
	this option to Exact and search for an exact server's name, otherwise
	you could receive a lot of output if many users from this server were banned.
	There is an extension that allows you to invert search results.
	For instance, you need to find all servers (not users) banned in your room.
	As we know, server addresses don't contain "@" character, so the task is easy:
/inbanlist ! @

New commands added that could be helpful
when ::muc::options(gen_enter_exit_msgs) is disabled.

---	Show all visitors of the current room
/visitors

---	Show all visitors of rooms that match *room*
/visitors room

---	Show visits made by someone whose nick or JID matches *nick*
/visited nick

---	Shows visits made by *nick*, to the rooms that match *room*
/visited nick
room

---	/visited command is enhanced. It's possible to search not only for nicks
	but also for jids, role, affiliation and version. The following keywords
	are reserved for such searches: jid, role, aff, hash, ver. Search query must not
	contain spaces (if it does, the whole construction is treated as a nick).
	The only exception is "ver" keyword. Anything that goes after it is treated
	as a single parameter, so for example the command
/visited ver Windows XP
	will return all entries containing words "Windows XP" in the version field.
	You don't need any keyword for nicks--just type it after the command.
	If you want to search for a nick that contains a keyword, cut it.
	For example, we look for the nick "jid revealer". The command should look
	like this: /visited id revealer
	Strict rules are not applied to terms searched with keywords, i.e. the command
/visited jid john
	will find john@jabber.org, johnson@jabber.org and bob@johnatan.info.
	Only nicks can be searched with strict rules.
	Unfortunately it's not possible (at least now) to make a separate search
	for client, client version and OS version.
	There is another subcommand for /visited which is named "log" and allows
	searching in a log file:
/visited log aff owner
someroom
	This will find all someroom's owners' entrances ever since you started
	logging in a file, not only during this session.
/visited log nick braveheart role admin ver Psi
someroom
	Even more flexible search! You can specify several queries in one line!
	Just remember that if you want to include search for a nick, specify this keyword
	so that the engine knew the nick is the word next to it, not the whole sentence.
	Also, "ver" query should be the last in the chain, as the engine takes all text
	that follows it as a search query.
/visited hash 8q9vzJIp9rr2u3+Y76hMLHyp00E=
	Sometimes searching for version hash can give a valuable results.
	Please see http://xmpp.org/extensions/xep-0115.html#ver for more info,
	but sometimes such hashes alone or with client and OS version can identify
	a certain visitor well enough without any jids. Please also note that
	hash is a variable information that can change after some reconfiguring
	or upgrading of your client or things like that, so don't trust it too much
	and always analyze the whole pack of available data.

--- An enumerated list styled as 'info' will be shown in the current chat window.
	In order to choose a line from it use a command explained above:
/bldjid ?n?
reason

where ?n? is an integer between 0 and the last item number.

--- There is a possibility to redirect /visit* and /bldhelp commands output
	to a special monitor window. See Customize section below.

--- There is a hotkey <Control-m> that is added to toggle between
	open/close states of the monitor.

--- To clear the current monitor window (not logs, neither the last search!)
	use the command:
/clearmon

--- You can set one or several items to be watched their entrance or nick change.
	Of course you have to be a moderator to be able to see visitors' real jids.
	But some of items are availbable for everybody. These are nicks, versions
	and version/caps hashes. To distinguish which parameter you would like to watch
	use the following keywords: nick, jid, hash, ver.
	Avoid special characters like * in nicks and jids to avoid false alarms.
	Use SomeUser instead of *SomeUser* although the second is a correct nick.
	The syntax is as follows:
/watch keyword parameter
	Please note in case of jids you should use a regexp to specify your needs.
	Also, note that you are allowed to have more than one hash but only one version
	because of the fact that it can consist of various words. If you set
	a new version to watch the old one will be overwritten. The same happens with
	the nick and with a regexp that represents jids.
-	These alarms you set are independent from each other (at the moment), i.e.
	if a person enters that satisfies only one of several alarms,
	only that alarm will shoot. So, now they are checked in "OR" way, and it's
	not a bad idea to have it in "AND" way, too, to obtain a possibility
	of alerting about entering somebody that only satisfies all of set alarms,
	to constrict the area of shooting.
-	You can point an action to perform when a user enters that satisfies
	any of your conditions. You can do it this way:
/watch keyword parameter
?command? type_of_exception exception reason Some reason.
	Let me explain.
.	?commad? can be one of these: say, devoice, kick or ban. If you set no command,
	a notification window will appear and you'll be able to chose some action
	manually. A command 'say' sends a private message to a watched person.
.	type of exception can be: !jid or !aff. Note that it starts with "!" character.
.	Since you should use regexp for !jid exception, you can set everything
	in "one word". There's no need to give more than one role/aff but you can do so.
	In case of !aff you can specify any xmpp valid role/affiliation,
	i.e.: member, admin, owner.
.	"reason" is a keyword that separates your reason from exceptions. Anything
	that goes after it will be used as a kick/ban reason. Later this behaviour
	will be reworked so that to drop this unnecessary keyword.
-	If you don't set exceptions you can put your reason directly after the command:
/watch ver Talkonaut
kick Talkonaut users are not welcome here!
-	Please note that currently /watch command is under development, so at the moment
	it will trigger (and devoice, kick or ban) any user that satisfies ANY
	of specified conditions (remember that they can be added except of ver).
	Be extremely careful when leaving Tkabber alone with the watcher enabled!
	The best solution at the moment is to create only one rule with (possibly)
	some exceptions, for example:
/watch hash elm8Y1EdFMgEdpCnBo00Gc3h+hj= OlM2m2jxGd7ClfEpFUk3rJLypzB=
ban !aff member reason You are not welcome here.
	This way you at least won't occasionally ban any members of your room.
-	You can delete an item from your watchlist using this command:
/unwatch keyword parameter
	The following command clears all parameters of a specified keyword:
/unwatch keyword all
	The following command clears the list:
/unwatch all
	To show the list use the command:
/listwatch
	REMEMBER that the option ::plugins::bldjid::options(rooms2log)
	affects notification: the plugin will only check entrances of watched jids
	to the rooms you have specified in this option! (See its description below.)

--- Autocompletion works for all these commands: write a couple
	of the first letters of a command and hit TAB one of more times.
-	Autocompletion also works in the same way for matching JIDs and nicks
	when you use commands /bldjid, /unban, /unbldjid
	after generating a user list by any of /visit* commands.
-	If there is no argument specified after the command, autocompletion
	starts checking nicks and only after them, JIDs (if there is a search result
	available). So if you choose autocompletion to specify a JID for banning,
	type at least the first letter of the JID you want to ban to avoid
	checking of all nicks (however, those that start with this letter
	will be offered, too). I will try to fix such inconvenient behaviour
	in the future.
-   Please note that autocompletion doesn't work if you have not created
	any user list, i.e. you have not used any of /visit* commands at least once.

--- Let's talk a bit about room protection. You probably know that rooms
	can be protected by captcha to avoid spam-bot or flood-bot attacks.
	As a more severe but more effective measure you can set your room
	temporarily as members-only until your attackers get tired. However,
	the captcha is annoying, especially for mobile clients, and an "elite"
	model is not suitable for most public rooms, so usually the owners unset
	these settings in their room configurations. But usually an attack
	begins unexpectedly and can "hang" a room in seconds. So, the earlier
	you notice it and the faster you act, the less inconvenient it will be
	for your visitors.
	The following commands offer a rapid access to these two setting:
/captcha ?n?
/monly ?n?
	?n? can be one of the following: '1', 'on' or 'ON' to set captcha or
	members-only for the current room, and '0', 'off' or 'OFF' to unset it.
	If you specify no parameter, a current state of a corresponding setting
	will be displayed in a chat window.

=====================
####  CUSTOMIZE  ####
=====================

There are Customize options for this plugin at
Tkabber -> Customize -> Plugins -> Bldjid

--- ::plugins::bldjid::options(enable_jids_gathering)
	Turns on JIDs gathering. Disabling it doesn't prevent
	/bldjid-like commands to work.

--- ::plugins::bldjid::options(rooms2log)
	Default value is empty which means that all available MUCs
	will be logged. If you only want to log certain rooms
	you can specify their jids separated with spaces here.

--- ::plugins::bldjid::options(log_file)
	Bldjid log file. If empty, logs won't be saved to file.
	It is useful if you want to recall who entered a certain room
	a certain date, even if you restarted Tkabber after it.
	Items of each entrance are tab-separated, so you can easily apply
	shell commands like grep, awk or sed for processing.
	Also, other useful information such as results of /bldjid, /unbldjid,
	and /amnesty commands will be logged. However, if you don't like
	logs to be saved on disk, just set this option to empty string.

--- ::plugins::bldjid::options(filter_admin_rooms)
	If you don't want rooms where you don't have admin privileges
	to be listed by /visit* commands, turn on this option (default setting).
	Bldjid still will gather logs for such rooms, it just won't display them.
	This behaviour could be useful if you'd like to know some JIDs
	in some non-anonymous room -- just turn this option off temporarily
	and do a search in that room.

--- ::plugins::bldjid::options(strip_resource)
	As being more informative, this option is OFF by default
	which means full JIDs with resource will be logged.
	However, if you prefer to log bare JIDs, just set it
	and resources will be stripped.

--- ::plugins::bldjid::options(log_role_aff)
	This option is turned OFF by default.
	This is for a better tracking of your visitors' roles and affiliation status.
	This option, if enabled, will show them to you in a chat or monitor window
	as well as will save this to a log file.

--- ::plugins::bldjid::options(log_ver_os)
	This option is also turned OFF by default.
	You might want to know client versions of your visitors in some cases.
	If you want to use this option please make sure you disabled the option
	::plugins::clientinfo::options(autoask) so that not to ask versions twice.

--- ::plugins::bldjid::options(log_ver_hash)
	Also disabled by default. If you enable it, bldjid will gather XEP-0115 hashes
	(please see its description for details). This information can be used
	to identify visitors but you shouldn't overestimate its value.
	This data can be changed if a user enables or disables some features
	of his or her client or upgrades it, or uses other software, or even
	forges it! Besides, slightly different versions can correspond
	to the same hash. Think twice before doing actions basing on this data.

--- ::plugins::bldjid::options(ver_timeout)
	Some paranoidally configured/hacked clients don't notify us
	about disabled version/os response, i.e. we never get any response.
	The first implementation of version request in this plugin
	was adding all user info to both array (current session) and log file
	at the end of a procedure that parsed version query response.
	Of course, if we never get response, such user becomes "invisible" to us.
	The current implementation adds user info (without version) to the array
	and then makes a request, setting an execution of a checking procedure
	after timeout. If we get version response we just look for a corresponding
	array entry and change its contents (which is previously set to "Timeout")
	to the version, save data to the file and cancel checking procedure execution.
	If we don't, after the timeout that procedure shoots and checks
	if the version was added. If we still have the version field set to "Timeout"
	we just leave the array as is and finally add the entry to the file
	with "Timeout" version to be aware of this user. If you see too many users
	with "Timeout" version you probably should increase the timeout wich is
	120 seconds by default.

--- ::plugins::bldjid::options(verbosity_level)
-	Minimum level means that there will be no repeated JIDs in each room list.
	However, if the same JID enters the same room with a different nick
	(or even changes his or her nick while staying in the room),
	such entrance will be also logged.
	Timestamps will also be added to every entry to keep it easier tracking
	user entrances.
-	Maximum level means that every entrance of every user will be logged.

--- ::plugins::bldjid::options(matching_rules)
-	"Exact" matching obliges you to provide exact parameters
	for /visit* commands to search (if you want to see any relevant result).
-	So the default setting is "Loose" matching that allows you
	to put only a group name or even its part instead of full room's JID.
	The same applies for nicks.

--- ::plugins::bldjid::options(custom_separator)
	Custom field separator for /visit* commands output. Default value is "||".

--- ::plugins::bldjid::options(redirect_output)
	Disabled by default.
	This option allows you to display /visit* and /bldhelp commands output
	in a special monitor window placed below the current chat input window.
	It can be closed manually and opened again by pressing <Ctrl-m>
	at any moment.
-	Closing this monitor window doesn't mean you lose your search result.
	You can still use ban and unban commands with a list number
	if you remember it, or using it with JID autocompletion.
	Even more, your search history is kept in each monitor window
	until you clear it by /clearmon command. However, keep in mind
	that only the last search result is used for "ban by item number"
	so use this mode carefully so that not to ban an innocent person :)
	Make sure you have invoked a new /visit* command before banning
	to get a fresh user list.
-	You can scroll monitor window up and down by pressing
	Alt-Shift-PgUp and Alt-Shift-PgDown correspondingly.
-	You cannot open/close monitor window manually if this option is disabled.

--- ::plugins::bldjid::options(send_chat_messages)
	Disabled by default.
	If enabled, chat system messages are published besides of logging
	user entrances. Unlike usual messages that are sent
	by ::muc::options(gen_enter_exit_msgs) these only appear once per JID.
	That's why it only works if Minimum verbosity level is chosen.

--- ::plugins::bldjid::options(log_length)
	Sets log length limit for each room. Default value is 0 that means no limit.
	If you want to enable log limiting enter some value (1000 should be enough
	for logging during several days in a highly populated room
	with Minimum verbosity level enabled). If you plan logging with Maximum
	verbosity level you might probably want to set a bigger value.
-	If you change this setting to a smaller value after some time of use,
	logs which length is higher than a new value will be trimmed down
	losing the oldest records (after a new user enters the affected room,
	which triggers adding a new element to log).
-	Please note that any non-integer or negative value is considered as 0.

--- ::plugins::bldjid::options(amoder)
	You can add here a regular expression that describes JID(s) to whom you'd like
	to assign a moderator role each time they enter a certain or any room
	where you have admin or owner privileges. If the list is empty, nothing will happen.

--- ::plugins::bldjid::options(amoder_groups)
	A space separated list of rooms can be given here if you only want
	to amoder those persons in a specific room(s). Please note this list
	will be applied to each JID that matches a regexp you provided above.
	I.e. if your regexp is "j(ohn|ames)@jabber.org" and the rooms are
	"room1@server.org room2@server.ru" you can't amoder john in room1 only
	and james in room2 only; both guys will become moderators in both rooms.
	Empty list means all rooms.

--- ::plugins::bldjid::options(watch_groups)
	This option is similar to the previous one but it is for rooms where
	you want watch for specific people entrances (and to apply some actions
	to them). In other words, when you set a /watch command the rest of rooms
	will be ignored.

================
####  MISC  ####
================

Plugin's name takes its origin from a Russian word "bldjad" and "JID."
It also could be taken as an acronym: "Ban Lousy Dorks (by) JID."
A big part of its code is stolen^W taken from "Urlcmd" plugin and muc.tcl module.
