##############################################################################
#                                            code written by Brandy@CrystalMUSH
#                                        for MUSH 2.0.10 patch level 5 or later
#
# These functions only work on systems that have upgraded to brandy_mailer.13.
#
# To use:  change references to #4167 to the dbref of the Parent Mail Object
#
#          (in vi:  :1,$s/#4167/<dbref of parent mail object>/g)
#
# I'm keeping this file separate from the normal +mail distribution, so
# people don't have to install it if they are uninterested in the 
# capability.
#
# As always, questions/comments/criticisms to cag@empros.com
#
# This file is available via anonymous FTP from 
# caisr2.caisr.cwru.edu (129.22.24.22) in file:
#   /pub/mush/mushcode/brandy_mailer_functions.1
#
##############################################################################
#
# +mail functions
#
#   mail_folders(player name or dbref)
#   mail_count(player name or dbref, folder name)
#   mail_sender(player name or dbref, message number, folder name)
#   mail_to(player name or dbref, message number, folder name)
#   mail_cc(player name or dbref, message number, folder name)
#   mail_bcc(player name or dbref, message number, folder name)
#   mail_subject(player name or dbref, message number, folder name)
#   mail_text(player name or dbref, message number, folder name)
#   mail_flags(player name or dbref, message number, folder name)
#   mail_note(player name or dbref, message number, folder name)
#   mail_time_sent(player name or dbref, message number, folder name)
#   mail_time_read(player name or dbref, message number, folder name)
#
# What good are they?
#
#   These functions may be used to automatically process some or all 
#   of your incoming mail.  
#
#   For example, you could set up a FAQ (frequently asked questions) 
#   mechanism, set up a filter to shove things with a particular subject 
#   line into a specific folder (perhaps '+add filter subject=FAQ folder=
#   faq requests').  Then have code that periodically goes through 
#   the requests in the FAQ folder and automatically responds.
#
#   +select folder faq requests;
#
#   @dolist lnum(mail_count(faq_maintainer, faq requests)) = 
#   {
#     +mail [mail_sender(faq_maintainer, add(##, 1), faq requests)] = 
#       Here's the FAQ you requested;
#     -[v(faq_data)];
#     --;
#     +delete [add(##, 1)]
#   };
#
#   @swi 1 = 1,
#   {
#     +flush
#   }
#
#   In the above example, the code would need to reside on the 
#   'faq_maintainer' player (since only players can use the +mail 
#   system), and 'faq_maintainer's delete option should be set to soft.
#
#   I personally use it in the +jobs code on CrystalMUSH, people who wish
#   to register jobs that they are looking for people for, people who want
#   to sign up for, or withdraw interest in registered jobs, send +mail
#   to a job_control character, which automatically processes its mail
#   once an hour.
#
#   Another thing they could be used for would be to customize your
#   own mail displays, although it wouldn't be very efficient to do
#   this.
#
# For each function, have #1 do:
#
#   @function/privileged <function>=<object>/<attr>
#
# Notes:  
#
#   setq()/r() are not used in these functions to avoid conflict with the user
#
#   Reminder:  function definitions created by @function are not stored
#   in the database, so they need to be re-created each time the MUSH is
#   started.  It is recommended that the Startup attribute for player #1
#   include code to set up all global functions (see wizhelp @function).
#
##############################################################################
#
# FUNCTION NAME:  mail_folders
#
# DESCRIPTION:
#
#   Return a list of defined folders for the specified player.
#   Since folder names can contain blanks, use | as a separator
#   between folder names instead of a blank.
#
#   You may only obtain this information for your own mailbox, 
#   unless you're a wizard.
#
# INPUT:  player name or dbref
#
# OUTPUT:  list of defined folders, each separated by a |
#          
#   If there are no folders defined, an empty string is returned.
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_FOLDERS) EXPECTS 1 ARGUMENT 
#   #-1 FUNCTION (MAIL_FOLDERS) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_FOLDERS) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_folders(brandy)
#   You say "main|notes|recruits|storage|things to do"
#   > say mail_folders(#3)
#   You say "main"
#


&MAIL_FOLDERS_FUNCTION #4167=switch(words(%0), 0, u(missing_argument, MAIL_FOLDERS, 1), u(mail_function2, switch(%0, me, %#, #*, %0, num(*%0)), %#, MAIL_FOLDERS, get_mail_folders))
&MAIL_FUNCTION2 #4167=switch(type(%0),PLAYER,switch(or(strmatch(%1, %0), hasflag(%1, wizard)), 1, u(%3, get(%vm/mailbox_%0), %2, %4, %5, %6, %7),u(permission_denied, %2)),u(unknown_player, %2))
#
# This is a helper routine for all the mail functions
#
# %0 - dbref of person mail_folders is being done on
# %1 - invoker
# %2 - invoking function name
# %3 - name of next function to call
# %4 - optional parameter to pass to function specified in %3
# %5 - optional parameter to pass to function specified in %3
# %6 - optional parameter to pass to function specified in %3
# %7 - optional parameter to pass to function specified in %3
#

&GET_MAIL_FOLDERS #4167=switch(0,words(%0),,secure(edit(trim(get(%0/folder-list)), %b, |)))
#
# DESCRIPTION:
#
#   This is a helper routine for function MAIL_FOLDERS.
#
# %0 - mailbox dbref
#

##############################################################################
#
# FUNCTION NAME:  mail_count
#
# DESCRIPTION:
#
#   Return the number of letters in the specified folder.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:
#
#    %0 - player name or dbref
#    %1 - folder name
#
# OUTPUT:  the number of letters in the specified folder
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_COUNT) EXPECTS 2 ARGUMENTS 
#   #-1 FUNCTION (MAIL_COUNT) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_COUNT) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_count(brandy, main)
#   You say "4"
#   > say mail_count(#2, things to do)
#   You say "6"
#


&MAIL_COUNT_FUNCTION #4167=switch(1,or(eq(words(%0), 0), eq(words(%1), 0)), u(missing_argument, MAIL_COUNT, 2), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_COUNT,get_mail_count, edit(%1, %b, $)))

#
# DESCRIPTION:
#
#   This is a helper routine for function MAIL_COUNT.
#
# %0 - mailbox dbref
# %1 - invoking function name (ignored)
# %2 - folder name (blanks converted to $'s)
#

&GET_MAIL_COUNT #4167=switch(0,words(%0), 0,words(get(%0/in-list-%2)))

##############################################################################
#
# FUNCTION NAME:  mail_sender
#
# DESCRIPTION:
#
#   Return the name of the player that sent the specified message.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:
#
#   %0 - player name or dbref
#   %1 - message number
#   %2 - folder name
#
# OUTPUT:  the name of the player that sent the specified message.
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_SENDER) EXPECTS 3 ARGUMENTS
#   #-1 FUNCTION (MAIL_SENDER) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_SENDER) MAIL MESSAGE NOT FOUND
#   #-1 FUNCTION (MAIL_SENDER) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_sender(brandy, 3, things to do)
#   You say "Kelson"
#

&MAIL_SENDER_FUNCTION #4167 = switch(1, or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)), u(missing_argument, MAIL_SENDER, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_SENDER,get_mail_sender, %1, edit(%2, %b, $)))

#
# DESCRIPTION:
#
#   This is a helper routine for function MAIL_SENDER
#
# %0 - mailbox dbref
# %1 - invoking function name 
# %2 - external message number
# %3 - folder name (blanks converted to $'s)
#

&GET_MAIL_SENDER #4167=switch(0,words(%0),u(msg_not_found, %1), and(gt(%2, 0),lte(%2, words(get(%0/in-list-%3)))),u(msg_not_found, %1), name(u(get_mail_sender2,%0,extract(get(%0/in-list-%3), %2, 1))))

#
# DESCRIPTION:
#
#   This is a helper routine for function MAIL_SENDER.
#
#   This is horribly mucky since for mail stored previous to 
#   version 13 of +mail has the sender stored in an atribute,
#   but for new mail sent after version 13 was installed, the
#   sender is determined by the 'owner' of the mailbox where the
#   mail originated from.
#
# %0 - mailbox dbref
# %1 - internal mail number
#

&GET_MAIL_SENDER2 #4167=switch(words(get(first(get(%0/in-%1-location))/out-[rest(get(%0/in-%1-location))]-sender)), 0, get(first(get(%0/in-%1-location))/owner_dbref), get(first(get(%0/in-%1-location))/out-[rest(get(%0/in-%1-location))]-sender))

##############################################################################
#
# FUNCTION NAME:  mail_subject 
#
# DESCRIPTION:
#
#   Return the subject line for the specified message.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:  
#
#   %0 - player name or dbref 
#   %1 - message number 
#   %2 - folder name
#
# OUTPUT:  the subject of message
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_SUBJECT) EXPECTS 3 ARGUMENTS 
#   #-1 FUNCTION (MAIL_SUBJECT) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_SUBJECT) MAIL MESSAGE NOT FOUND
#   #-1 FUNCTION (MAIL_SUBJECT) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_subject(brandy, 1, main)
#   You say "Fwd:  Hi! Sugestions enclosed..."
#


&MAIL_SUBJECT_FUNCTION #4167 = switch(1, or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)), u(missing_argument, MAIL_SUBJECT, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_SUBJECT,get_mail_attribute,%1, edit(%2, %b, $), subject,out))

##############################################################################
#
# FUNCTION NAME:  mail_time_sent 
#
# DESCRIPTION:
#
#   Return the date and time that the specified message was sent.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:  
#
#   %0 - player name or dbref 
#   %1 - message number
#   %2 - folder name
#
# OUTPUT:  date/time the message was sent
#
# Possible errors:
#
#      #-1 FUNCTION (MAIL_TIME_SENT) EXPECTS 3 ARGUMENTS
#      #-1 FUNCTION (MAIL_TIME_SENT) UNKNOWN PLAYER
#      #-1 FUNCTION (MAIL_TIME_SENT) MAIL MESSAGE NOT FOUND
#      #-1 FUNCTION (MAIL_TIME_SENT) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_time_sent(brandy, 1, main)
#   You say "Tue Jun 21 14:57:17 1994"
#


&MAIL_TIME_SENT_FUNCTION #4167 = switch(1, or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)), u(missing_argument, MAIL_TIME_SENT, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_TIME_SENT,get_mail_attribute,%1,edit(%2, %b, $),time_sent, out))

##############################################################################
#
# FUNCTION NAME:  mail_text 
#
# DESCRIPTION:
#
#   Return the text of the specified message.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:  
#
#   %0 - player name or dbref 
#   %1 - message number
#   %2 - folder name
#
# OUTPUT:  text of message
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_TEXT) EXPECTS 3 ARGUMENTS 
#   #-1 FUNCTION (MAIL_TEXT) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_TEXT) MAIL MESSAGE NOT FOUND
#   #-1 FUNCTION (MAIL_TEXT) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_text(brandy, 2, main)
#   You say "This is some test text in a +mail message."
#


&MAIL_TEXT_FUNCTION #4167 =switch(1,or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)),u(missing_argument, MAIL_TEXT, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_TEXT,get_mail_attribute,%1,edit(%2, %b, $),text,out))

##############################################################################
#
# FUNCTION NAME:  mail_to 
#
# DESCRIPTION:
#
#   Return the to list of the specified message.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:  
#
#   %0 - player name or dbref 
#   %1 - message number
#   %2 - folder name
#
# OUTPUT:  'to' list of message (prettified)
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_TO) EXPECTS 3 ARGUMENTS 
#   #-1 FUNCTION (MAIL_TO) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_TO) MAIL MESSAGE NOT FOUND
#   #-1 FUNCTION (MAIL_TO) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_to(brandy, 2, main)
#   You say "Rose, Samira and Kelson"
#


&MAIL_TO_FUNCTION #4167 =switch(1,or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)),u(missing_argument, MAIL_TO, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_TO,get_mail_attribute,%1,edit(%2, %b, $),to,out))

##############################################################################
#
# FUNCTION NAME:  mail_cc 
#
# DESCRIPTION:
#
#   Return the CC list of the specified message.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:  
#
#   %0 - player name or dbref 
#   %1 - message number
#   %2 - folder name
#
# OUTPUT:  'CC' list of message (prettified)
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_CC) EXPECTS 3 ARGUMENTS 
#   #-1 FUNCTION (MAIL_CC) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_CC) MAIL MESSAGE NOT FOUND
#   #-1 FUNCTION (MAIL_CC) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_cc(brandy, 2, main)
#   You say "wizards (global mail alias) and Rose"
#


&MAIL_CC_FUNCTION #4167 =switch(1,or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)),u(missing_argument, MAIL_CC, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_CC,get_mail_attribute,%1,edit(%2, %b, $),cc,out))

##############################################################################
#
# FUNCTION NAME:  mail_bcc 
#
# DESCRIPTION:
#
#   Returns a boolean indicating if the player specified in the first 
#   argument is in the BCC list for the specified message.  1 - yes, 0 - no.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:  
#
#   %0 - player name or dbref 
#   %1 - message number
#   %2 - folder name
#
# OUTPUT:  1 - user is in BCC list for message, 0 - user is not
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_BCC) EXPECTS 3 ARGUMENTS 
#   #-1 FUNCTION (MAIL_BCC) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_BCC) MAIL MESSAGE NOT FOUND
#   #-1 FUNCTION (MAIL_BCC) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_bcc(brandy, 2, main)
#   You say "0"
#


&MAIL_BCC_FUNCTION #4167 =switch(1,or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)),u(missing_argument, MAIL_BCC, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_BCC,on_bcc_list,%1,edit(%2, %b, $)))
#
# DESCRIPTION:
#
#   This is a helper routine for function MAIL_BCC
#
# %0 - mailbox dbref
# %1 - invoking function name
# %2 - external message number
# %3 - folder name (blanks converted to $'s)
#

&ON_BCC_LIST #4167=switch(0,words(%0),u(msg_not_found, %1),and(gt(%2, 0),lte(%2, words(get(%0/in-list-%3)))),u(msg_not_found, %1),sign(member(u(get_mail_attribute_out, %0, extract(get(%0/in-list-%3), %2, 1), bcc-expanded), get(%0/owner_dbref))))
&MAIL_NOTE_FUNCTION #4167 =switch(1,or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)),u(missing_argument, MAIL_NOTE, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_NOTE,get_mail_attribute,%1,edit(%2, %b, $),note,in))

##############################################################################
#
# FUNCTION NAME:  mail_note 
#
# DESCRIPTION:
#
#   Return whatever note is registered with the specified message.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:  
#
#   %0 - player name or dbref 
#   %1 - message number
#   %2 - folder name
#
# OUTPUT:  Either a null string, or whatever note is registerd
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_NOTE) EXPECTS 3 ARGUMENTS 
#   #-1 FUNCTION (MAIL_NOTE) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_NOTE) MAIL MESSAGE NOT FOUND
#   #-1 FUNCTION (MAIL_NOTE) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_note(brandy, 2, main)
#   You say "This is a note previously registered with +add note=<text>"
#


&MAIL_TIME_READ_FUNCTION #4167 =switch(1,or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)),u(missing_argument, MAIL_TIME_READ, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_TIME_READ,get_mail_attribute,%1,edit(%2, %b, $),time_read,in))

##############################################################################
#
# FUNCTION NAME:  mail_time_read 
#
# DESCRIPTION:
#
#   Return the date and time that the specified mail message was read.
#   A zero is returned if the letter has not been read yet.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
# INPUT:  
#
#   %0 - player name or dbref 
#   %1 - message number
#   %2 - folder name
#
# OUTPUT:  Either zero, or the date and time that the letter was last read.
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_TIME_READ) EXPECTS 3 ARGUMENTS 
#   #-1 FUNCTION (MAIL_TIME_READ) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_TIME_READ) MAIL MESSAGE NOT FOUND
#   #-1 FUNCTION (MAIL_TIME_READ) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_time_read(brandy, 2, main)
#   You say "Wed Jun 22 18:42:41 1994"
#


&MAIL_FLAGS_FUNCTION #4167 =switch(1,or(eq(words(%0), 0), eq(words(%1), 0), eq(words(%2), 0)),u(missing_argument, MAIL_FLAGS, 3), u(mail_function2,switch(%0, me, %#, #*, %0, num(*%0)),%#,MAIL_FLAGS,get_mail_attribute,%1,edit(%2, %b, $),flags,in))

##############################################################################
#
# FUNCTION NAME:  mail_flags 
#
# DESCRIPTION:
#
#   Return a list of the registered flags for a specific mail message.
#   An empty string is returned if there are no flags.
#
#   You may only obtain this information for messages in your own
#   mailbox, unless you're a wizard.
#
#   NOTE:  The flags are not interpreted.
#
#     Mapping:    U --> Urgent
#                 R --> Registered
#                RR --> Reply Requested
#                 P --> Private
#                 D --> Marked for Deletion
#                 M --> Marked
#                 S --> Saved
#
# INPUT:  
#
#   %0 - player name or dbref 
#   %1 - message number
#   %2 - folder name
#
# OUTPUT:  An empty string or a list of registered flags.
#
# Possible errors:
#
#   #-1 FUNCTION (MAIL_FLAGS) EXPECTS 3 ARGUMENTS 
#   #-1 FUNCTION (MAIL_FLAGS) UNKNOWN PLAYER
#   #-1 FUNCTION (MAIL_FLAGS) MAIL MESSAGE NOT FOUND
#   #-1 FUNCTION (MAIL_FLAGS) PERMISSION DENIED
#
# EXAMPLE:
#
#   > say mail_flags(brandy, 2, main)
#   You say "U RR"
#


&GET_MAIL_ATTRIBUTE #4167=switch(0,words(%0), u(msg_not_found, %1), and(gt(%2, 0),lte(%2, words(get(%0/in-list-%3)))),u(msg_not_found, %1), u(get_mail_attribute_%5,%0, extract(get(%0/in-list-%3), %2, 1),%4))
#
# DESCRIPTION:
#
#   This is a helper routine for the +mail functions.
#
# %0 - mailbox dbref
# %1 - mail function name
# %2 - external message number
# %3 - folder name (blanks converted to $'s)
# %4 - which attribute to get
# %5 - 'in' or 'out'
#

&GET_MAIL_ATTRIBUTE_OUT #4167=u(first(get(%0/in-%1-location))/out-[rest(get(%0/in-%1-location))]-%2)
#
# DESCRIPTION:
#
#   This is a helper routine for functions:
#     MAIL_SUBJECT, MAIL_TIME_SENT, MAIL_TEXT, MAIL_TO, MAIL_CC.
#
# %0 - mailbox dbref
# %1 - internal mail number
# %2 - which attribute to get
#

&GET_MAIL_ATTRIBUTE_IN #4167=u(%0/in-%1-%2)
#
# DESCRIPTION:
#
#   This is a helper routine for functions:
#     MAIL_NOTE, MAIL_FLAGS, MAIL_TIME_READ.
#
# %0 - mailbox dbref
# %1 - internal mail number
# %2 - which attribute to get
#

&MISSING_ARGUMENT #4167=#-1 FUNCTION (%0) EXPECTS %1 ARGUMENT(S) 
&UNKNOWN_PLAYER #4167=#-1 FUNCTION (%0) UNKNOWN PLAYER
&MSG_NOT_FOUND #4167=#-1 FUNCTION (%0) MAIL MESSAGE NOT FOUND
&PERMISSION_DENIED #4167=#-1 FUNCTION (%0) PERMISSION DENIED