##############################################################################
# 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