
	This is not the last word in the database/hash structure.
	I essentialy used this document as a notepad so I could
	remember what I did as I programmed.  It can be very
	usefull though, if you're adding new featurs or changing
	the core code.  I'll try to edit this another time so it's
	easier to understand and more complete.


	- Description of this document -
	This file tries to describe the hash databases, what they're used
	for and it's here to keep track of them all, so we can use the
	information to prevent bugs in the program and to add new commands.

	- How to read this document -
	When describing my hash elements the key will be refered to as
	%somethinghere% and the the name as "somethinghere" while the value
	would be a description of what's contained.  Also, keys are ALWAYS
	in lowercase so that I can be sure they'll match properly.  I store
	data, before changing the case, if it's needed later.  An example
	is the storing of a nickname.  Chatters like they're nicks to be
	case sensative, at least to appear that way.  Using this method
	I'm able to store their nicks with their case sensative setting
	so that others viewing their info will see the nick they registered
	and not the lowercase key.  Later, we'll have a command that will
	allow them to change the case appearance.  When you see me write
	%somehash{%keyname%}{some/stuff/here} it always means
	%somehash{%keyname%}{some} 	%somehash{%keyname%}{stuff}
	%somehash{%keyname%}{here}.  It just takes up less space.

	You'll see that there appear to be keys of keys and in fact I think
	that's excatly what I've done.  Hey, it works for me and it's easy
	for me to understand.  This time around I attempted to examine the
	possibilities of linking keys inside seperate databases so that I
	could delete sections of several entire data base segments simply
	by deleting ONE key.  This would make things a whole lot easier
	but, if it's possible, I fear it may make things a bit too
	difficult to understand.

	---------------------------------------------------------------------
	NICKNAME AND CHANNEL TRACKING - recording data
	---------------------------------------------------------------------
	nickname and data tracking
	---------------------------------------------------------------------
	%nicks{%keynick%} - <- lowercase nick as key
	$nicks{%keynick%}{user/host/kill/name/nick/chans/} \
		{%killnick% / %keychan} {timestamp}

	user		- one word username, after the ! (nick!user@host)
	host		- see above
	kill		- key into the rest, hard word
	name		- contents of the users name (real name)
	nick		- real case nickname
	chans		- hard key, next is keychannel of channels this nick is on
	%keychan%	- lowercase keyname for channel, only a key, no content
	%killnick	- a user can be marked for death on a number of nicks
			- this key is assocciated with a timestamp for killing
			- this particular nick
	timestamp	- the time after which %killnick% will be killed or changed.


			nick, user, host, name} <- as is
			{chans}{%keychan} <- lowercase key and inside is the real case 
			{ident}{chans} <- list of channels they identified as founder
			{ident}{nicks} <- list of nicks they identified as owner

			# I might change this later but the channel hash built this way:

			%chans{#channel}{users}{nicks on channel}{their modes}
			%chans{#channel}{modes}{channel modes} <- {key if +k}
			%chans{#channel}{topic} <- {contents of topic}
			%chans{#channel}{bans}{masks, hosts, ips of banned people}
			%chans{#channel}{count} <- {number of users on channel}


	%opers{%keynick%}{ircop}

	%servdir	- Lowercase service nicks are the keys to the data
			- that tell us which sub directory to look in for
			- that particular service: $servdir{%servnick%} points
			- to the sub directory where the commands are for that
			- particular service such as OperServ.  We build this
			- database so they can have more flexibility and can
			- use any nicknames they like for the services.  The
			- directory names are still static, operserv, nickserv,
			- like that.
	---------------------------------------------------------------------
	channel name and data tracking
	---------------------------------------------------------------------
	%chans{%keychan%}{modes/users/bans/chan/topic} \
		{%mode% / %nicks% / %masks% }{%mode%}

	%pos{%mode}{%mask%}
	%neg{%mode}{%mask%}

	%pos and %neg are also defined for each mode setting, either for bans,
	ops, voice or channel modes. Any mode that can be placed once such as
	+ or - imsp ( channel modes ) have a single key and no other data.  If
	the mode is + or - k then the key is recorded under the %mode% key and
	if + l the limit is recorded under the %mode%, howevever, - l does not
	come with a parameter and need only be indicated as key under %neg.
	Modes that can be placed more than once, + or - obv ( user/nick modes )
	have an additional key which is the mask for ban or the nick for others.
	---------------------------------------------------------------------
	%keychan%	- lowercase channel name
	chan		- real case channel name
	modes		- key only, no content, next key %mode% for chan mode
	modes}{%mode - channel mode, if l(limit) or k(keyd) then this %mode
			  contains the key or limit number, inside the KEY.
	users		- key only, next is nicks and mode of that nick
	users}{%nick- all keys, %nick is lowercase key of nick on channel
	%nick}{%mode- see the relationship, %mode is key only, no content here,
			  and contains the mode, so you can say if ?blah{%nick%}{o}.
			  sould contain all modes, v/o/ What else? none right? but
			  it will record anything tossed at it in sub mode .
	bans		- key only, next is masks only as keys
	bans}{%mask	- end of line here, all we need are the masks
	---------------------------------------------------------------------
	NICKNAME AND CHANNEL SERVICES
	---------------------------------------------------------------------

	%rnicks{%keynick%}{nick/name/user/host/seen/timereg/secure/email/url \
	/uin/opnote/rank/timestamp/lasttime/%access%}{item/hide}

	There are a few items that can be seen in info that users may not
	wish to be seen, changeable items. These have an {item} key so
	we can then attach a {hide} key/value pair. It's pretty obvious
	what items can be manualy changed and can be viewed as well.

	Registered nicknames and their associated data.
	-------------------------------------------------------------
	%keynick%	- Lowercase key to registered nick data.
	nick		- The case sensative version they wanted
	pass		- case sensative password or phrase
	user		- The first part of the host, ( ~user1 )!bob@bob.com
	host		- Host line ~user1!bob@( bob.com )
	name		- What they typed for their info, "Real Name" "nunya"
	seen		- last time seen
	timereg		- time/date it was registered
	secure		- kill/nick change enabled?
	email		- free hand, a place for an email address
	host		- last host name they were
	url		- free hand, used for url
	uin		- free hand, used for icq number
	opnote		- if they're an oper they can set the note
	rank		- each nick has a rank, opers get numbers, nicks get none
			  this sets the $opers hash where we check for ranks/oper
	timestamp	- timestamp of time registered, we use this to see if they've
			  droped their nick since a rank setting. works great.
	lasttime	- last time they identified, in case we expire somday
	access%		- {access}{%somemask%} a list of keys that are masks, access
			  list
	hide		- only good for email/uin/url and opnote, hides the element
				  for a persons nick INFO
	-------------
	memos%		- {memos}{list/count/nicks/total/%index%}{%keynick%}{%index%} \
					{text/flag/date/timestamp/nick}
	-------------
	list		- just a flag so we know they listed, checked by DEL. we
			  remove this flag on each database write so they don't DEL
			  memos they didn't read, they might not understand the
			  sequencing, which is reindexed on each write.
	nicks		- a sub key, empty, with keys and associated data
	total		- total number of memos from all nicks
	memos{%index- this is a special key/nick element. it gives us the
			  nickname assocciated with a key for easy lookup/delete
			  it contains the keynick, this is a key/value pair.
	%keynick%	- lowercase nick of sender
	%index%		- A unique number, incremented using last {total}
	text		- actually text/body of memo
	count		- when this is 0 we delete the nick, or they get listed
	flag		- to show if a memo was read, deleted, new
	date		- date/time memo was delivered
	timestamp	- internal info, used for expired if not read, if we use it
	nick		- real case nick of sender
	

{nick}{%index%} <- "contents"
	%keynick%	- senders lowercase key
	total		- total memos from this nick
	------------- {%index}{date}{timestamp}{text}
	%index%		- unique number for this sender, eg: 1, 2, 3 whatever.
			  The memo itself is underneath the this key.
	date		- so they know when the memo was sent
	timestamp	- so WE know when the memo was sent.  we might use this
			  later to expire memos after a certain time limit.
	text		- what else, the contents of the memo itself.

		 <-memo, memos are here now so we can
			  just delete everything in one pass. I think this will work
			  nicely. A memo is keyed by the nick that sent it and is
			  indexed with numbers so we can list them for each nick
			  that sent.


	-------------------------------------------------------------
	Registered channels and their associated data.

	%rchans{%keychan%} {chan/pass/owner/modes/topic/url/title \
		/secure/timereg/timestamp \
		/locked/access/akick/owner/ranks/action/game} {nick/user/host/hash}

	Also there's {rank} on almost all, if not all, changable items
	in the hash, eg. $rchans{$keychan}{ranks}{topic} = 2; # aops change topic
	-------------------------------------------------------------
	%keychan%	- Lowercase key to registered channel data.
	chan		- case sensative channel name
	pass		- the channel OWNER password
	owner		- Some might be familiar with FOUNDER, this is similar.
			  this is a hard key only.
	owner}{nick - the owner nickname
	owner}{user	- the owners username
	owner}{host	- the owners hostname
	modes		- This is a key holder, locked modes for the channel,
			  typicaly +nt, other modes are handled by other commands,
			  like limit or key.
	modes}{item - The actualy modes, key to value
	modes}{state- on or off, if off then it shows off in info, if ON
	modes}{hash	- This is a key to keys of modes for faster code
	hash}{%mode	- mode letters applied but SET MODES, we made this hash
			  so it's easier, and quicker, to itterate over the modes
			  to find which ones were changed by unauthorized users.
			  then it shows the modes in info.
	secure		- modes that can't be set on the channel or it's users.
			  item, state and rank.
	secure}{hash - key into the mode letters
	hash}{%mode	- like with {modes}{hash}{%mode%} excatly
	topic		- This is a key holder, the last topic athorised by chanserv,
			  used by the TOPIC command.
	topic}{item - The actual topic
	topic}{state - on or off, if on then topic is set for channel on join and
			  shows up in the info, if off no topic is set and shows off.
	url		- This is a key holder, attatch a url to your channel.
			  item, state and rank here too.
	title		- This is a key holder, what your channel is about, replaces
			  description/desc. It's just some info about what the
			  channel is for. It's not required to register.
			  /msg chanserv register #chan <pass word> this also has
			  item, state and rank.

	timereg		- time and date the channel was registered last
	timestamp	- we might use it later, the old database doesn't
			  have a timestamp so all new databases being created
			  will use the date that the database was converted.
	locked		- operator/admin level block, so unauthorized users
			  can't join the channel.  some locked channels can
			  show specific data such as services messages etc.
			  locking a channel of this nature will watch for
			  unauthorized joins and disable loging when this happens.

	Below you'll see that the area is commented out.  Before I decided
	to add aop and sop I created a ranks system where each registered
	nick has a rank assocciated with channel access.  Now we can just
	go through the ranks and see who's who instead of asking aop and
	sop, that was tedious before, to say the least.  Now it's all in
	one area and we don't use masks anymore for these access routines. 
	Only registered nicks or ident owner can have access to channel
	service features.

	access		  - a list of nicks and assocciated ranks for this channel
	access{%nick  - the lowercase registered nickname as key
	%nick}{nick   - the real case nickname
	%nick}{rank	  - the rank assocciated with this nick a number from
				    0 - 3, owner, sop, aop, temp op, respectively.
	%nick}{timestamp - This is the timestamp found in the registered nick's
				  - timestamp, we compare it against the nick to see if
				  - it's been dropped since there were ranked. if the stamps
				  - don't match we don't consider them ranked.
##
#	aop			- {aop}{%nick% %host%}/{%mask%} in lieu of a nick
#				  you can use a mask.  If you supplied a nick it
#				  must be registered.  You can use a mask instead.
#				  The host is from the nicks data base and has no
#				  specific meaning yet.  It's just there for info.
#	sop			- {aop}{%nick% %host%}/{%mask%} excatly like aop
#				  but I'm considering making this registered nicks
#				  only because of the damage they can cause.
##
	akick		- {akick}{item}{%mask%}{reason} <-(note) list of masks
				  that chanserv will check on a nick then kick if
				  matched. The reason can be anything and is info
				  for the person being kicked, or for the OWNER
				  so they remember why.
	action		- a key to more keys. this is a rank system that holds
				  rank numbers and actions.  for instance, if you set
				  join to rank 3 then only ops can join the channel, all
				  others will be kicked.
	action}{join/mode/topic/kick/oper/rank}{rank}
				  all used seperately of course, we can change these ranks
				  later but when a user registers the channel they're set
				  to defaults. action}{rank is who has authority to make
				  changes to the root action ranking.
	game		- a list of nicks and points that are in the game
			  for this particular channel.
	game}{rank	- who can set options, add, del, start, stop etc.
	game}{state	- on or off, changed with START/STOP respectively
	game}{keywords  - these are indexed into $rgames{%keyword}{%keychan}
	game}{nicks	- base key for nicks list of keys
	nicks}{%keynick	- The lowercase nickname as key for the nickname
			  that is in the game. for this channel.
	%keynick}{nick	- key/value, their true case nick for visualisation
	%keynick}{score - key/value, their score, a single number
	---------------------------------------------------------------------
	Game service database
	---------------------------------------------------------------------
	Most of the game information, nicks, score, points and such are
	conveniently stored in the registered channel hash which also has
	a list of keywords. These keywords are indexed into the game service
	database $rgames with their extended key being that of the channels
	that have these keywords. Here's how the relationship works.

	/msg GameServ START #House Trivia MindGames BrainTeasers

	Will create keys in the registered channel like so

	$rchans{'#house'}{game}{keywords}{trivia}
	$rchans{'#house'}{game}{keywords}{mindgames}

	You get the idea.  And the games list, $rgames, will have this
	same list as its base keys

	$rgames{trivia}{'#house'}
	$rgames{mindgames}{'#house'} etc...

	You can find this game by doing
	/msg GameServ FIND triva brainteasers

	If more than one of your keywords match the same channel then
	the weight goes up for that channel. After your keywords are
	exhausted the weight is tested to see which channel matched
	best and list's that first as "BEST MATCH: #House" and then a list
	of those that had one of your keywords.


	---------------------------------------------------------------------
	Oper serv hash's and variables, these are for IRC Operators
	---------------------------------------------------------------------
	%opers{%keynick%}{rank}
	---------------------------------------------------------------------
	%keynick%	- The lowercase nick as key
	{rank}		- their rank number, listed in service.conf
	-----------------------------------------------------------
	%opcoms		- This is used to hold everything associated
			  with irc operator service, access and
			  administration. The access structure follows
			  the same arrangement as the registered channels
			  hash, accept there's only one key "comands"
			  instead of various keys, as you find for
			  channels.  Instead, we have other structures
			  under other keys, like maybe servers/links/
			  klines, I'm not sure how much I'll expand on
			  this but you should get the idea by now.
	-----------------
	%opcoms{access/bans/ranks}{rank/item}

	Command access keys and values for operserv.  These are seperated
	into varying levels of control.  for instance, you may not want
	your level 3 opers to be able to mkill but they can kill using
	operserv.

	%opcoms{access/link/kill/mkill/mode}{rank/link/kill/mkill/mode}
	unfolds like this
	$opcoms{ranks}{rank}	- minimum rank rquired to rank others
	$opcoms{access}{rank}	- who can change ranks on items
	$opcoms{access}{link}	- who can change rank on link command
	$opcoms{link}{rank}	- what rank can add links
	$opcoms{access}{kill}	- who can change rank on kill command
	$opcoms{kill}{rank}	- what rank can use the kill command
	... and on and on

	you see how the structure is formed.
	{access} is a list of items that are listed in the root of this
		 hash as well.

	Here's how it works, it's just like the channels.  Our access key
	has a list of items as keys as well.

	{ranks}{rank}	<- minimum rank requirement to rank another.
			   regardless of this rank, you can only rank ONE
			   below you.
	{access}{rank}	<- who can change access ranks on access settings...
			 - example: you want all your level 2 opers to be
			 - able to change ranks on access setings. these
			 - opers can /msg operserv set access mode 4
			 - and all level 4 opers can use the mode command.
			 - you'd effect that access like this:
			 - /msg operserv set access access 2
	{access}{mode}	<- who can change the rank on mode
	{mode}{rank}	<- who can set modes, 
	{pass}		<- this is the administrators password. anyone
			 - that has this password or phrase has control
			 - over every aspect of operserv and, depending
			 - on your configuration, servers as well.
			 - This password rotates through a list. Every time
			 - it's used it changes to the next in the list.
			 - Make sure your trusted admins have a list of
			 - your recent password settings.
	{suspend}	 - if this key exists, only the admin can access
			 - anything assocciated with operserv.  This is
			 - to prevent a mutiny.  Even in a system where
			 - your trusted admins went rogue, anyone with
			 - admin access can kill the services.

	There are too many elements to list here for now.  I have to start
	work on making these elements a reality now.  After that I may have
	time to update this listing.

	---------------------------------------------------------------------
	common variables that should be set when we need them
	---------------------------------------------------------------------
	$servnick		- Nickname of the current service querried
				  such as NickServ.
	$comline		- The valid command line that was typed. We use this
				  to return information to the user for assistance.
				  We use this so that, if an admin wants to rename
				  the commands, this will happen semlessly simply
				  by renaming the command file.


** I'm still updating this document 



