powxel 

Date....: 11 JUL 2001
Author..: Axel Trocha (axel@trocha.com)
Aim.....: Database and advanced Scripting support in Powwow
Tools...: Powwow 1.2.5 and FreeM 0.6.3



--- INTRO -------------------------------------------------------------------

I just hacked in this readme, just to offer a quick overview and make the
project avail as soon as possible to those who want to test it.

Everyone who reads this text most likely heard of Powwow or even uses it, but
never head of FreeM. Powwow is one of the best unix-based MUD clients, while
FreeM is a programming language with an integrated database. 

I am using Powwow since I mud, which is not all the long. Using Powwow I did
uncountable nice scripts, but still I was not too happy with its scripting
abilities. Everything seems to be squeezed into one line and I was missing
database support.

Since 1991 I am coding in Mumps. Mumps is BASIC-like, string-oriented
programming language with an integrated database. It is mostly used in medical
environments, where huge amounts of data have to be stored and worked with.
There were several Mumps vendors, but they all were bought by one company. So
we started the Free-Mumps project (later renamed to Free-M) in 1998, which
aimed to supply a free Mumps environment. For several reasons the project
broke apart in mid 1999. I am still enhancing and using it.



--- POWWOW -------------------------------------------------------------------

I used Powwow 1.2.5 as base, applied some patches so it compiles with 2.4.x
kernel and added some misc stuff:

- time wariables: year, month, day, hour, min, sec, time
  e.g. #print (year+month+day)

- changed the #edit command, so you can set the local-editing-editor at
  runtime.
  e.g. #ed /usr/bin/vi  or  #ed vi   etc
  


--- The Merge ----------------------------------------------------------------

I threw the source of Powwow and FreeM into one directory and started working
on it, till it compiled without errors. Then I added a new powwow command
#mumps, so you can switch to the FreeM environment from within Powwow.

So there are basically two possible modes/environments/prompts: Powwow and
FreeM. It is possible to switch between those modes and exchange data.

After starting the program it starts in Powwow mode and if you used Powwow
before you will think nothing has changed. You can use Powwow like before,
except another Powwow command was added: #mumps
Typing #mumps will switch completely to the FreeM environment. The prompt
will change to "freem>". You can get back to powwow by typing h[alt].
(h[alt] means you can either type: h or ha or hal or halt)

But we will stay in the FreeM mode for a while. After switching to FreeM from
Powwow, all current Powwow variables are imported. Since variables in FreeM
cannot consist of dollars ($) and underscores (_), it will cut those away.
For instance the powwow last_line variable will be lastline in FreeM. If you
want to check what variables are set at that moment you can type w[rite]


	* W C>#mumps
	#invoking mumps interpreter...
	#type h[alt] to exit
	freem>w
	lastline=You will climb if necessary.
	prompt=* W C>
	
	freem>h
	
	#exiting mumps interpreter...
	* W C>


While you are in FreeM mode you can also issue powwow commands, like you would
be in Powwow mode. For instance you can just type #emu test, #var or #connect
or whatever. That way you could export variables back to powwow, do #emulates
so that powwow #actions trigger, or do #mark's ...


	* W C>#mumps
	#invoking mumps interpreter...
	#type h[alt] to exit
	freem>#var
	#the following variables are defined:
	#($last_line = "9 players on.")
	#($prompt = "* W C>")
	
	freem>#zap main
	#connection on `main' closed.
	#no connections left. Type #quit to quit.
	
	freem>h
	
	#exiting mumps interpreter...
	
	#no open connections. Use '#connect main...


Ok, that still isn't really interesting. Let do something cooler. Hm, before
we do some set of actions to handle a secret door database, we start of with
a narrate-saver:




*) "THE NARRATE SAVER"

How do we start? First we need a powwow action which triggers on the keyword
"narrates". To make it fool-proof, we could also trigger on the narrate-color-
codes. In MUME, if you use "cha col all def", it will be yellow. So our powwow-
script could look something like this:

	
	#ac >+getnarr ^\033[33m$1 narrates &2\033[0m=#mumps save^narrate
	#al nl=#mumps show^narrate


Typing "#mumps " will switch too the FreeM environment, import
the powwow variables, execute the mumps-script and go back to powwow. The
mumps-script is nothing else than a textfile with the extention ".m". So
"#mumps narrate" would execute the mumps script "narrate.m". In above example
I use "#mumps save^narrate", which will call the file "narrate.m" and start at
the label "save". Below you see how "narrate.m" could look like:

	
	narrate	;
		h
	save	;--- save last narrate into database
		s idx=$o(^narrate(""),-1)+1
		s ^narrate(idx)=lastline
		w lastline,!
		h
		;
	show	;--- show last 10 narrates from database
		s idx="",cnt=0
		d line
		f  s idx=$o(^narrate(idx),-1) q:idx=""!(cnt=9)  d
		. s cnt=cnt+1
		. w ^narrate(idx),!
		d line
		h
		;
	line	;--- just draw a seperator line
		s green=$c(27)_"[32m"
		s norm=$c(27)_"[0m"
		w green,$tr($j("",80)," ","-"),norm
		q



Some explanations:
I usually use abbreviations. Well, its just a habbit:
	
	d => do		(to execute a function/procedure)
	f => for	(for loop)
	h => halt	(switch back to powwow)
	q => quit	(quit procedure)
	s => set	(set a variable)
	w => write	(write to screen)

If you see a ^ it means "do not look in the local environment, but rather
into the database/on the harddrive". When writing to the database you are not
bound to predefined keys, you can do what you like. Some examples

	s ^test(1,"name")="axel
	s ^test(1,"phone")="2323-232-32"
	s ^test(1,"sex")="m"
	s ^test(2,"name")="thomas"
	s ^test(2,"phone")="3232-232-22"
		:

	s ^name("axel")=1
	s ^name("thomas")=2
		:


so the table ^test will be the file ^test on harddrive and ^name will be
the file^name on the harddrive...

I am not going to describe the Mumps language here, I will rather search the
internet if I find some nice language docs. At this place I will only give a
short overview.




*) "SECRET-DOOR-DATABASE"

How do we do that? Well, do a powwow #action which triggers on the room colors.
No a lot more choices we have. After "cha col all def" in MUME, the rooms will
be colored green, so we could trigger on that. Note that tells might be green
too, so we should take care of that. But in that example I just ignore the fact
that tells screw up our "getroom" action. Oki, the powwow-script could look
like following:


	#ac >+getroom ^\033[32m&1\033[0m=#mumps room^secrets
	#al os=#mumps open^secrets
	#al cs=#mumps close^secrets
	#al adds=#mumps adds^secrets
	#al door={#var $door=$1;#print ("door set to: "+$door)}


I set the current "door" variables by using the powwow alias door. So if you
want to set the door to "thickbrush", type "door thickbrush". Certainly there
are nicer ways to do that, but I wanted it to be short. The mumps code could
look file below:


	secrets	;
		h
	room	;--- set room variable
		w $g(lastline),!
		x "#var $room="_p1
		h
		;
	open	;--- check database and issue an open on all matches
		n nroom
		s nroom=$$c($g(room)) i nroom="" h
		s door=""
		f  s door=$o(^secrets(nroom,door)) q:door=""  d
	        . x "#send ("_$c(34)_"open "_door_$c(34)_")"
		h
		;
	close	;--- check database and issue a close on all matches
		n nroom
		s nroom=$$c($g(room)) i nroom="" h
		s door=""
		f  s door=$o(^secrets(nroom,door)) q:door=""  d
	        . x "#send ("_$c(34)_"close "_door_$c(34)_")"
		h
		;
	gets	;
		n nroom,txt
	        s nroom=$$c($g(room)) i nroom="" h
	        s door=""
	        f  s door=$o(^secrets(nroom,door)) q:door=""  d
		. s txt="   "_$c(27)_"[32m"_door_$c(27)_"[0m"
		. x "#emu "_txt
		h
		;
	adds	;--- the the current door name to the database
		n nroom
		s green=$c(27)_"[32m"
		s norm=$c(27)_"[0m"
	        s nroom=$$c($g(room)) i nroom="" h
		i $g(door)="" h
		s ^secrets(nroom,door)=""
		w !,"Added: ",green,door,norm," to room ",green,nroom,norm,!
		h
		;
	c(t)    ;--- convert room name:
		;--- name all lowcase, remove spaces, dashes and 's
		;--- remove "a" "an" and "the"
		;--- (this makes us less vulnerable to room name changes)
	        n new,i
	        s t=$tr(t,$zmu,$zml)
	        f i=1:1 s word=$p(t," ",i) q:word=""  d
	        . i word="an"!(word="a")!(word="the") q
	        . s new=$g(new)_word_" "
	        s new=$tr($g(new)," -'"_$c(34))
	        q new


I am tired of writing this now, I will do more later this week....

Axel