; User defined functions

; =====================================================================================
; Customize:

$homeworld="YourHomeWorld"

; for each bot instance, create a string named alias_BotsName containing aliases.
; this will affect the @botcmd macro which determines when the bot responds to chat,
; so you can use the aliases when directing commands at the bot.
; (note: bot's actual name can't contain any spaces, using this system)
; ------------------------------------------------------------------------------------
; NOTE: There is a currently problem with this system: if you run any bot instances
; without an alias defined here, you will get a lot of error messages. To avoid this,
; I've deactivated the aliases until I fix the problem, but if you want to use the
; aliases now, you can do so by finding the @botcmd macro definition in this file,
; and moving the semicolon from the first to the second definition. If you do that,
; remember that you MUST have an alias here for every bot name you use, to avoid
; error messages!
; ------------------------------------------------------------------------------------
$alias_Mags="Maggy|Magsbot|MB"

@triviawait=30000
@triviapause=5000

$midiobject="midispk.rwx"

; for random movement
@random_move=30000

; SET YOUR AVATAR TYPES HERE TO USE $title, $timeofday macros
; arg=avtype
; put female avatar numbers here:
$f_avatars="0 7 9 10 11 12 13 19 20 21 27 29 30 31 32 35 41 42 44 45 47 49 52 54 55 58 59 60 62 63"
; put neutral avatar numbers here:
$n_avatars="2 3 4 5 6 14 15 16 17"

; $title returns "lady", "gentleman" or "friend" depending on avatar gender
; ~1=@avtype
$title[@]=$if[@ind[$str[~1],$f_avatars," "],"lady",$if[@ind[$str[~1],$n_avatars," "],"friend","gentleman"]]

; put your ID and priv. password here...
; (used by some buttons to create a new instance, etc.)
@userid=0
$password=""

@userid2=0
$password2=""

; ==============================================================================
; Standard macros:
; last revised 10/25/02

; Note: some of these are pretty complicated,
; but you don't need to understand the definition
; in order to use the macro. :)

; sometimes mbot needs to check if the bot is in a'tuin or a'tuin+  :)
@atuin=@eq[$worldname,"a'tuin"]
@atuin2=@eq[$worldname,"a'tuin2"]
@atuinplus=@eq[$worldname,"a'tuin+"]

; for logging surveys
$ologitem[@,@,@,@,@,@,$,$,$,@,@]=$fmt_["%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s",~1,~2,~3,~4,~5,~6,$quote[~7],$quote[~8],$quote[~9],~10,~11]

$arg_model=$unqarg[@if[@axis3,7,5]]
$arg_desc=$unqarg[@if[@axis3,8,6]]
$arg_act=$unqarg[@if[@axis3,9,7]]
@arg_tilt=@if[@axis3,@arg[5],0]
@arg_roll=@if[@axis3,@arg[6],0]
@arg_owner=@arg[@if[@axis3,10,8]]
@arg_time=@arg[@if[@axis3,11,9]]

@sessof[$]=@if[@ispresent[~1],@sessionof[~1],0]

@SDKval[$]=@val[$left[~1,@len[~1]-1]]*@if[@ipos[$asn[x_,$uc[$right[~1,1]]],NW],1000,@if[@ipos[$x_,SE],-1000,0]]

@frac[@]=~1-@int[~1]
@round[@]=@int[~1]+(@frac[~1]>=.5)
$round[@,@]=$fmt["%s.%s",@int[~1],@round[@frac[~1]*10^~2]]

$addcommas[$]=$if[1+@loop[@asn[L_,@len[~1]]+@asn[r_,@L_%3]+@asc[$asn[s2_,$left[~1,@r_]]]+@asn[i_,@r_+1],1,@int[@L_/3],1][@asc[$asn[s2_,$cat[$if[@asc[$s2_]>=0,$cat[$s2_,","],$s2_],$sub[~1,@i_,3]]]]+@asn[i_,@i_+3]],$s2_,$s2_];

; ----------------------------------
; trig

; angle to turn in order to face coords
; ~1=ns
; ~2=we
@facezx[@,@]=@int[@arctan2[~2-@we,~1-@ns]/@pi*1800]

; angle to turn in order to face toward av
; e.g.:  FACE @faceav[@sessionof[$avname]]
; ~1 = av session
@faceav[@]=@int[@arctan2[@avx[~1]-@we,@avz[~1]-@ns]/@pi*1800]

; ~1=session to face toward
; ~2=session doing the facing
@avfaceav[@,@]=@int[@arctan2[@avx[~1]-@avx[~2],@avz[~1]-@avz[~2]]/@pi*1800]

;----------------------------------
; colors

; 6-digit hex -> rwx format (3 values 0-1)
; 04ff00 -> 
$rwx[$]=$fmt["%s %s %s",(@red[@dec[~1]]/255),(@green[@dec[~1]]/255),(@blue[@dec[~1]]/255)]

; 6-digit hex -> rgb format (3 values 0-255)
$rgb3[$]=$fmt["%s %s %s",(@red[@dec[~1]]),(@green[@dec[~1]]),(@blue[@dec[~1]])]

; 3 values 0-255 -> 1 value 0-FFFFFF
@rgb[@,@,@]=(~1*65536+~2*256+~3)

; 3 values 0-255 -> 6-digit hex
$rgb[@,@,@]=$hex[@rgb[~1,~2,~3]]

; single r,g or b value 0-255 extracted from value 0-FFFFFF
@red[@]=(@shr[~1,16]&255)
@green[@]=(@shr[~1,8]&255)
@blue[@]=(~1&255)

;----------------------------------

; add leading 0 to numbers < 10
$ft_[$]=$if[@len[~1]=1,$cat["0",~1],~1]
$ft[@]=$ft_[$str[~1]]

;----------------------------------------------------------------------
; string and chat parsing functions

$binary[@]=$fmt["%s%s%s%s%s%s%s%s",@shr[(~1&128),7],@shr[(~1&64),6],@shr[(~1&32),5],@shr[(~1&16),4],@shr[(~1&8),3],@shr[(~1&4),2],@shr[(~1&2),1],~1&1]

$LF=$cat[$asc[13],$asc[10]]
$tab=$asc[9]
$LF127=$cat[$asc[10],$asc[127]]

; use these with the HEAR event to distinguish which mode the speaker used
@said=(@atr[CHAT_TYPE]=@chattype[said])
@whispered=(@atr[CHAT_TYPE]=@chattype[whisper])
@broadcast=(@atr[CHAT_TYPE]=@chattype[broadcast])

; for backward compatibility with earlier versions of MBot:
@whisperingto[$]=@selected[~1]

;@botcmd=@eq[$botname,$word[1]]||@val[$fmt["@word_in[$alias_%s,$word[1],""|""]",$botname]]
@botcmd=@eq[$botname,$word[1]]

; test if speaking to bot; either by using botname or by whispering
@tell=(@botcmd||@whispered)

; test name to see if it's a bot name (=has brackets)
@isbot[$]=@eq[$left[~1,1],"["] && @eq[$right[~1,1],"]"]

; delimiters (dividers between words) for chat
$chatdelims=" .,;?!"

; returns word n of chat string
$word[@]=$unquote[$par[$chat,$chatdelims,~1]]

; returns segment of chat string between specified words, inclusive
; ($words_ is implemented internally)
$words[@,@]=$words_[$chat,~1,~2,$chatdelims]

; index of word in chat string
@word[$]=@ind[~1,$chat,$chatdelims]

; index of word in chat string (wildcard)
@wrd[$]=@wind[~1,$chat,$chatdelims]

; number of words in the chat string
@words=@par[$chat,$chatdelims]

; find word in a chat string directed at bot;
; also matches same word ending in "s",
; i.e. @w[apple] would find "apple" or "apples"
@w[$]=(@tell&&(@word[~1]||@word[$cat[~1,"s"]]))

; find phrase in a chat string directed at bot:
;@phr[$]=(@tell&&@str_in[~1,$chat,$chatdelims])
; ********** CHANGED **********
@phr[$]=(@tell&&@ipos[~1,$chat])

; number of the first word in the chat string other than the bot's name
; i.e., =1 if bot name isn't used, =2 if bot name is used.
@w1=@if[@botcmd,2,1]

; first word other than bot name:
$w1=$word[@w1]

; second word other than bot name:
$w2=$word[(@w1+1)]

; remainder of chat string after first word, not counting bot name
; e.g. if chat is "mags follow the big avatar" then $ww would be "the big avatar"
$ww=$tail[$chat,(@botcmd<>0)*(@len[$word[1]]+1)+@len[$w1]+2]

; chat is directed at bot, and word1 is specified word
@cmd[$]=(@tell&&@eq[$w1,~1])

; slash command (like /join, etc.)
@cmd_[$]=@eq[$left[$w1,1],"/"]&&@eq[$tail[$w1,2],~1]

; avname is in control list
@isctrl[$]=@itemnum[control,~1]

; search a string for any one of a list of items:
; returns true if any item in the list is found in the string
; (returns index in list of found word or 0 if not found)
; IMPORTANT: you need to call RESETLIST before using this macro, 
; in order for it to work properly.
; ~1=name of list
; ~2=string to search in
; e.g. @wordin[mylist,$chat]
@wordin[$,$]=@wordinlist[~1,~2,$chatdelims]
@inlist[$]=@wordinlist[~1,$chat,$chatdelims]

; search string for any one of a group of delimited words/phrases;
; returns true if any word/phrase in the group of words/phrases is found in the string;
; e.g. @word_in["apple|plum|kiwi fruit|orange",$chat,"|"] will return true if
; "apple", "plum", "kiwi fruit" or "orange" are in the chat string.
; ~1=group of words/phrases to look for, separated by delimiter ~3
; ~2=string to search in, e.g. $chat
; ~3=delimiter(s) between looked-for words/phrases (PHRASE MUST MATCH LOOKED-IN EXACTLY)
; e.g. @word_in["apple|peach|kiwi fruit",$chat,"|"]
@word_in[$,$,$]=@iposw[~1,~2,~3,$chatdelims]
@instr[$]=@iposw[~1,$chat,"|",$chatdelims]

; the same as @instr
@wi[$]=@instr[~1]

; like @wi but only looks at first word in chat
@wi1[$]=@word_in[~1,$w1,"|"]

; @word_in using $chat and | between looked-for words/phrases, directed at bot
@ww[$]=(@tell&&@wi[~1])

; get a random string from a string list; arg=list name
$rnd[$]=$litem[~1,1#@itemcount[~1]]

; insert a char into a position in a string
; ~1=string to insert into, ~2=string to insert, ~3=position to insert at
$ins[$,$,@]=$cat[$left[~1,~3-1],~2,$tail[~1,~3+1]]

; remove n chars from a position in a string
; ~1=string, ~2=position, ~3=num of chars to remove
$del[$,@,@]=$cat[$left[~1,~2-1],$tail[~1,~2+~3]]

; field update function:
; use this to update a delimited "field" within a string;
; for example if $s="grape,blueberry,peach" then
; $updf[$s,2,"plum",","] would return "grape,plum,peach"
; args:
;  ~1=string of delimited data
;  ~2=number of field to replace
;  ~3=new value for the field
;  ~4=delimiter (usually a comma)
; note: use $ar_ or @ar_ to retrieve (comma-delimited) fields from a string
; NOTE! this macro uses $s_, @nn_ and @p_ as temporary variables
$updf[$,@,$,$]=$cat[$words_[~1,1,~2-1,~4],$if[~2=1,"",~4],~3,$if[~2=@par[~1,~4],"",~4],$words_[~1,~2+1,@par[~1,~4],~4]]

; read a line from a file, removing the eol at the end if any
; $trimr[$read[~1]] will work too but trailing spaces will be lost
;$readln[@]=$if[@eq[$right[$asn[x_,$read[~1]],1],$asc[13]],$left[$x_,@len[$x_]-1],$x_]

; extract an argument from a comma-delimited sequence of values:
; e.g. if $s="grape,plum,peach" then $ar_[$s,2] would be "plum"
@ar_[$,@]=@val[$par[~1,",",~2]]
$ar_[$,@]=$par[~1,",",~2]

; like $ar_ but removes quotes
$unqar_[$,@]=$unquote[$ar_[~1,~2]]

; same as @ar_, $ar_, except specifically for string named $mk
; (for use by bookmark buttons)
@arg[@]=@ar_[$mk,~1]
$arg[@]=$ar_[$mk,~1]

; same as $unqar_, except specifically for string named $mk
$unqarg[@]=$unquote[$arg[~1]]

@quoted[$]=@eq[$left[~1,1],""""]&&@eq[$right[~1,1],""""]

; remove first and last chars (presumably quotes) from a string
$dequote[$]=$tail[$left[~1,@len[~1]-1],2]

; replaced by internal function:
; remove quotes from a string (i.e. remove first & last chars ONLY IF they are quotes)
;$unquote[$]=$if[@eq[$left[~1,1],""""]&&@eq[$right[~1,1],""""],$dequote[~1],~1]

; absolute value
@abs[@]=@if[~1<0,-~1,~1]

; text comparison, equals or not-equals
@eq[$,$]=(@icmp[~1,~2]=0)
@neq[$,$]=(@icmp[~1,~2]<>0)

; logical negation
@not[@]=(~1=0)

; alphabetic comparisons
@lt[$,$]=(@icmp[~1,~2]<0)
@gt[$,$]=(@icmp[~1,~2]>0)
@lte[$,$]=(@icmp[~1,~2]<0) || (@icmp[~1,~2]=0)
@gte[$,$]=(@icmp[~1,~2]>0) || (@icmp[~1,~2]=0)

; ---------------------------------------------------------------------
; for specialized uses:

; translate aw name to bone name;
; assumes bn_$avname=$bonename
; (for use with aw scoreboard)
$bonename[$]=$v_[$cat[bn_,~1]]

; for scavenger hunt item indices, like "0000001000220":

; ~1=string, ~2=item number ~3=new value; returns new string
; e.g. $flags["abcdef",3,"x"] returns "abxdef"
$flags[$,@,@]=$cat[$left[~1,~2-1],$str[~3],$tail[~1,~2+1]]

; ~1=string ~2=item number; returns item value
; e.g. @flag["12345",3] returns 3
@flag[$,@]=@val[$sub[~1,~2,1]]

@hasitem[@]=@if[@asn[r_,@dbfindfirst[$fmt["Name='%s'",$avname]]],@flag[$dbtfield[player,@r_,items],~1],0]

;-----------------------------------------------------------------------
; location functions:

; true if coords are within safe zone specified by safe list
; ~1=name of safe list
; ~2,~3=z,x coordins
@safezx[$,@,@]=((~2<@litem[~1,1])&&(~2>@litem[~1,2])&&(~3<@litem[~1,3])&&(~3>@litem[~1,4]))

; true if avatar is within safe zone specified by safe list
; containing the N,S,W,E borders (in that order)
; ~1=name of safe list
; ~2=avatar session
@safe_[$,@]=@safezx[~1,@avz[~2],@avx[~2]]

; true if avatar is within safe zone specified by default safe list "safe"
; (to set safe list, use "Set SafeN","Set SafeS", "Set SafeW", "Set SafeE" buttons)
; ~1= avatar session
@safe[@]=@safe_["safe",~1]

; distance between coords, ignoring altitude
; z1,x1; z2,x2
@dist2[@,@,@,@]=@sqr[(@abs[~1-~3]^2+@abs[~2-~4]^2)]

; distance between coords in 3 dimensions
; z1,x1,y1; z2,x2,y2
@dist3[@,@,@,@,@,@]=@sqr[((@sqr[(@abs[~1-~4]^2+@abs[~2-~5]^2)])^2+(@abs[~3-~6])^2)]

; distance between 2 avs, ignoring altitude
; args=session numbers
@avdist2[@,@]=@dist2[@avz[~1],@avx[~1],@avz[~2],@avx[~2]]

; distance between 2 avs in 3 dimensions
; args=session numbers
@avdist3[@,@]=@dist3[@avz[~1],@avx[~1],@avy[~1],@avz[~2],@avx[~2],@avy[~2]]

; distance between bot and av in 2 dimensions
; arg=session number
@botdist2[@]=@dist2[@avz[~1],@avx[~1],@ns,@we]

; distance between bot and av in 3 dimensions
; arg=session number
@botdist3[@]=@dist3[@avz[~1],@avx[~1],@avy[~1],@ns,@we,@alt]

; is a location near another location?
; ~1,~2,~3 = z1,x1,y1
; ~4,~5,~6 = z2,x2,y2
; ~7=distance considered "near"
@nearzxy[@,@,@,@,@,@,@]=(@abs[(~4-~1)]<~7)&&(@abs[(~5-~2)]<~7)&&(@abs[(~6-~3)]<~7)

; is a location near the bot?
; ~1,~2,~3 = z,x,y
; ~4=distance considered "near"
@nearbot[@,@,@,@]=@nearzxy[~1,~2,~3,@ns,@we,@alt,~4]

; same as @nearbot, kept for backward compatibility, yuck
@near[@,@,@,@]=@nearbot[~1,~2,~3,~4]

; is a location near an avatar?
; ~1=avatar session
; ~2,~3,~4 = z,x,y
; ~5=distance considered "near"
@nearav[@,@,@,@,@]=@nearzxy[~2,~3,~4,@avz[~1],@avx[~1],@avy[~1],~5]

; is an av near the bot?
; ~1=av session
; ~2=distance considered "near"
@botnearav[@,@]=@nearzxy[@ns,@we,@alt,@avz[~1],@avx[~1],@avy[~1],~2]

; is an av near another av?
; ~1=av1 session
; ~2=av2 session
; ~3=distance considered "near"
@avnearav[@,@,@]=@nearzxy[@avz[~1],@avx[~1],@avy[~1],@avz[~2],@avx[~2],@avy[~2],~3]

; convert SDK coordinates into AW Browser coordinates:
$AWB[@,@,@,@]=$fmt["%s%s %s%s %sa %s",@abs[~1/1000],$if[~1<0,"S","N"],@abs[~2/1000],$if[~2<0,"E","W"],(~3/100),(~4/10)]

;-----------------------------------------------------------------------
; time&date functions:

; VRT ------------------------------

; ***** NOTE! ******
; for @vrtime function to work properly, edit below:
; put your own time zone here, e.g. -5 for ET, -8 for PT etc.
@tz=-5
; set this to "1" during daylight savings time, 0 during standard time
@dst=0

; MBot gives you a choice of 2 different sets of macros for dealing with date/time:

; ......................................
; this method uses delphi's method, a floating point number = days since 1899,
; with the fraction indicating the time of day:

; current vr time as a float
@vrtime=(@time-@tz/24-@dst/24-2/24+@vrtoffset/86400)

; current vr time as a string
$vrtime=$time[@vrtime]

; current vr date as a float...
@vrdate=@date+(@vrtime>=@if[@dst,@timeof["22:00"],@timeof["21:00"]])

; ......................................
; alternate method uses C time function, an integer = seconds since 1/1/1980
; (this is also the method used in propdumps to indicate when an object was created)

; translate ctime to vr time
@vrt_[@]=(~1-(@tz*3600)-2*(3600)-@dst*(3600)+@vrtoffset)

; current vr time as integer
@vrt=@vrt_[@ctime]

; current vr time as string
$vrt=$ctime[@vrt]

; translate ctime integer to vr time as string
$vrt_[@]=$ctime[@vrt_[~1]]

; ---------------------------------

; whichever "@now" function is used will affect all other time functions;
; comment out (=put a semicolon in front of) the one you DO NOT want to use:

; this version returns your computer's local time
@now=@date+@time

; this version returns VR time
;@now=@vrdate+@vrtime

; date + time string
$now=$cat[$date[@now]," ",$time[@now]]

; date string
$datenow=$date[@now]

; time string
$timenow=$time[@now]

@hour=@hourfromtime[@now]%12
@minute=@minfromtime[@now]
@second=@secfromtime[@now]
@msnow=@msfromtime[@now]

@pm=@eq[$right[$timenow,2],"PM"]
@am=(@pm=0)

; for backward compatibility
@timestamp=@ctime

; hour of dawn
; e.g. if sunrise_hr=7 then sunrise sky is shown from 7:00am to 7:59am, and day sky begins at 8:00am
@sunrise_hr=8

; hour of sunset
; e.g. if sunset_hr=7 then sunset sky is shown from 7:00pm to 7:59pm, and night begins at 8:00pm
@sunset_hr=6

@dawn=(@am && (@hour=@sunrise_hr))
@dusk=(@pm && (@hour=@sunset_hr))
@twilight=(@dawn||@dusk)
@day=((@am && @hour>@sunrise_hr && @hour<>12)||(@pm && (@hour<@sunset_hr || @hour=12)))
@night=((@pm && @hour>@sunset_hr && @hour<>12)||(@am && (@hour<@sunrise_hr || @hour=12)))

@sunset=@dusk

@morning=(@am && @hour<12 && @hour>=6)
@afternoon=(@pm && (@hour<6 || @hour=12))
@evening=(@pm && (@hour<>12 && @hour>=6))
@weesmall=(@am && (@hour<6))

$timeofday=$if[@morning,"morning",$if[@afternoon,"afternoon","evening"]]

@msecinday=86400000
@hrlen=1/24
@minlen=1/24/60
@seclen=1/24/60/60

;-----------------------------------------------------------------------
; timers:

; standard timer number constants:
; these timers are used in the standard behavior table:
@movetimer=1
@trivtimer=2
@miditimer=3
@storytimer=4
@autosavetimer=5
@recover=6
@scorebd=7
@daytimer=8

; timers used for recording (in the standard behavior table) are numbered 100 and up:
; be careful not to use the same timer numbers for something else
@rectimer=100

; timers used for playback (in the standard behavior table) are numbered 200 and up;
; be careful not to use the same timer numbers for something else
@playtimer=200

; ----------------------------------------------------------------------

; userevent numbers

@helpreq=1000
@triviareq=1001
@trivianoansw=1002
@playbackend=1003
@storybegin=1004
@usercmd=1010

;-----------------------------------------------------------------------
; macros for frequently-used AW attributes, just for convenience:

$avname=$atr[AVATAR_NAME]
$chat=$atr[CHAT_MESSAGE]
$worldname=$atr[WORLD_NAME]
@avsession=@atr[AVATAR_SESSION]
@chatsession=@atr[CHAT_SESSION]
@ns=@atr[MY_Z]
@we=@atr[MY_X]
@alt=@atr[MY_Y]
@yaw=@atr[MY_YAW]
@gesture=@atr[MY_GESTURE]
@type=@atr[MY_TYPE]

@objnum=@atr[OBJECT_NUMBER]

; ip number from string
@ip[$]=@shl[@val[$par[~1,".",4]],24]|@shl[@val[$par[~1,".",3]],16]|@shl[@val[$par[~1,".",2]],8]|@val[$par[~1,".",1]]

; ip string from number
$ip[@]=$cat[$str[~1&255],".",$str[(@shr[~1,8]&255)],".",$str[(@shr[~1,16]&255)],".",$str[(@shr[~1,24]&255)]]

; for use with ejection list
@ejectaddr=@atr[EJECTION_ADDRESS]
$ejectaddr=$ip[@ejectaddr]
@ejectstart=@atr[EJECTION_CREATION_TIME]
@ejectexpire=@atr[EJECTION_EXPIRATION_TIME]
$ejectcomment=$atr[EJECTION_COMMENT]

; -----------------------------------
; old nearlist function names
; preserved for backward compatibility
$listnext=$nearnext
@listnext=@nearnext
; -----------------------------------

; LIST FUNCTIONS ==================================================================

; **********
; these are primitive functions for accessing and verifying numbered variables.
; (numbered var = a var with a name like "$mylist:1" or "@mylist:1", etc.).
; you should use the higher-level functions in the section after this instead
; when possible; their names are more descriptive.
; ("iv" = indexed variable = numbered var)

; NOTE: internal functions:
; (i.e. functions implemented in mbot.exe, not as macros)
;
; @var[$]       numeric variable value by name
; $var[$]       string variable value by name
; @isvar[$]     test for numeric var existence by name
; @isstrvar[$]  test for str var existence by name

; $var_[@]      global variable value by index (str OR numeric)
; $varname_[@]  global variable name by index (str OR numeric)

; @varcount      number of all global vars, string & numeric
; @varncount[$]  number of global vars with specified prefix, e.g. @varncount["$mylist:"]
;
; @ivnum[$,$,@]      item number from string list name and item value
; @ivnum_[$,@,@]     item number from numeric list name and item value
; (3rd argument = item number to start search at)

; functions for traversing lists; use RESETLIST or RESETLIST_ to start at top of list
; ...for string lists:
; @nextnum[$listname]      returns the item number
; $nextitem[$listname]     returns the item value (string)
; @nextindex[$listname]    returns the index of the item in the global var list
; ...for numeric lists:
; @nextnum_[$listname]     returns the item number
; @nextitem[$listname]     returns the item value (number)
; @nextindex_[$listname]   returns the index of the item in the global var list

; create a real var name from list name+item num
; note: cannot currently use $fmt function in a macro! $cat is used instead:
$ivname[$,@]=$cat[~1,":",$str[~2]]

; get item value by item num:  (string list,numeric list)
; ~1=list name ~2=item num
$ivar[$,@]=$var[$ivname[~1,~2]]
@ivar[$,@]=@var[$ivname[~1,~2]]

; check if item exists:  (string list,numeric list)
; ~1=list name ~2=item num
@isstrivar[$,@]=@isstrvar[$cat[~1,":",$str[~2]]]
@isivar[$,@]=@isvar[$cat[~1,":",$str[~2]]]

; get item value, but without error if doesn't exist:
; (string list,numeric list)
; ~1=list name ~2=item num
$iv_[$,@]=$v_[$ivname[~1,~2]]
@iv_[$,@]=@v_[$ivname[~1,~2]]

; **********
; these are higher-level functions for lists; 
; use these instead of above functions when possible

; get the value of a variable from it's name;
; like @var,$var except no error message if variable is missing;
; returns 0 or "" if variable not found
@v_[$]=@if[@isvar[~1],@var[~1],0]
$v_[$]=$if[@isstrvar[~1],$var[~1],""]

; to retrieve an item from a list  (string list,numeric list)
; 1st arg=listname, 2nd arg=item number:
; ~1=list name ~2=item num
$listitem[$,@]=$ivar[~1,~2]
@listitem[$,@]=@ivar[~1,~2]

; to retrieve item from a list without error message;
; returns "" or 0 if variable is missing:
; (i.e., this is a SEARCH FOR AN ITEM BY NUMBER)
; ~1=list name ~2=item num
$litem[$,@]=$iv_[~1,~2]
@litem[$,@]=@iv_[~1,~2]

; check if item with specified item number is in the list
; (string list,numeric list)
; (i.e., this is a CHECK FOR AN ITEM'S EXISTANCE, BY NUMBER)
; ~1=list name ~2=item num
@isitem[$,@]=@isstrivar[~1,~2]
@isitem_[$,@]=@isivar[~1,~2]

; find item number from item value (string list,numeric list).
; list must not have item number 0 or negative item numbers for these functions to work;
; returns 0 if item not found
; (i.e., this is a SEARCH FOR AN ITEM BY VALUE)
; ~1=list name ~2=item value
@itemnum[$,$]=@ivnum[~1,~2,0]
@itemnum_[$,@]=@ivnum_[~1,~2,0]

; the number of items in the list  (string list,numeric list)
; ~1=list name
@itemcount[$]=@varncount[$listprefix[~1]]
@itemcount_[$]=@varncount[$listprefix_[~1]]

;--------------------------------------------------------------------
; functions for manipulating names of variables or lists:

; convert list name to variable prefix, e.g. "test" -> "$test:"
; (string list,numeric list)
$listprefix[$]=$cat["$",~1,":"]
$listprefix_[$]=$cat["@",~1,":"]

; checks if a variable name is a valid list variable name;
; (NOTE: does NOT check if the var actually exists, 
; only if the var name is in list name format).
; e.g. @ismember["$mylist","$mylist:n"]=true
; (can also be used with any prefixed variable,
; not just numbered variables; e.g. $mylist:blah);
; (you can use this when looping thru global vars,
;  checking each var to see if it's a member of a 
;  particular list or not)
@ismember[$,$]=@eq[~1,$prefixof[~2]]

; extracts item num from list variable name (i.e. "$mylist:2" -> 2)
@itemnumof[$]=@val[$suffixof[~1]]

; extracts suffix of list item name (i.e. "$mylist:blah" -> "blah")
$suffixof[$]=$par[~1,":",2]

; extracts prefix (including $ or @) of list item name (i.e. "$mylist:blah" -> "$mylist")
$prefixof[$]=$par[~1,":",1]

; =====================================================================================

; END of UserDefs !