The Mail Modules

The Mail modules operate at a higher level than the Net modules, interacting with external mail packages such as mail, mailx, sendmail, or a POP3 server in the case of Net::POP3. This section describes some of the MailTools modules, Mail::Folder, and the other mail-related modules that were mentioned at the beginning of this chapter.

Send Email with Mail::Mailer

The Mail::Mailer module interacts with external mail programs. When you use Mail::Mailer or create a new Mail::Mailer object, you can specify which mail program you want your program to talk to:

use Mail::Mailer qw(mail);

Another way to specify the mailer is:

use Mail::Mailer; $type = 'sendmail'; $mailprog = Mail::Mailer->new($type);

in which $type is the mail program. Once you've created a new object, use the open function to send the message headers to the mail program as a hash of key/value pairs, in which each key represents a header type, and the value is the value of that header:

# Mail headers to use in the message %headers = ( 'To' => 'you@mail.somename.com', 'From' => 'me@mail.somename.com', 'Subject' => 'working?' );

This code represents headers in which the recipient of the mail message is you@mail.somename.com, the mail was sent from me@mail.somename.com, and the subject of the mail message is working?.

Once %headers has been defined, it is passed to open:

$mailprog->open(\%headers);

You then send the body of the message to the mail program:

print $mailprog "This is the message body.\n";

Close the program when the message is finished:

$mailprog->close;

A practical example of using Mail::Mailer might be a command line-driven application that works much like the Unix mail program, either reading STDIN until end-of-file or mailing a file specified on the command line.

Mail::Mailer uses the environment variable PERL_MAILERS to augment or modify the built-in mailer selection. PERL_MAILERS is specified in the following format:

"type1:mailbinary1;mailbinary2;...:type2:mailbinaryX;...:..."

The possible types are listed for the new method below.

The following methods are defined in Mail::Mailer.

$mailer = new Mail::Mailer [type, command] 

Constructor. Creates a new Mailer object representing the message to be sent. If the optional arguments are specified, the value of commanddepends on type, which can be one of:

• mail
• Uses the Unix mail program. command is the path to mail. The module searches for mailx, Mail, and mail, in that order.
• sendmail
• Uses the sendmail program. command is the path to sendmail.
• test
• Used for debugging. Calls /bin/echo to display the data, but doesn't actually send any mail. command is ignored, if specified.

If no arguments are specified, the Mailer object searches for executables in the above order and uses the first one found as the default mailer.

$mailer->close 

Closes the mail program.

$mailer->open(\%hashref) 

Sends message headers to the mail program. The headers are passed via a reference to a hash, in which each key is the name of a header, and the value is the contents of the header field. The value can be either a scalar or a reference to an array of scalars.

Better Header Control with Mail::Send

Mail::Send is built on top of Mail::Mailer, which means that you can also choose the mail program that sends the mail. Mail::Send has implemented the methods to, cc, bcc, and subject to replace the %headers hash used in Mail::Mailer.

Mail::Send uses the open method to open the mail program for output; it is built on Mail::Mailer's new method, so that:

# Start mailer and output headers $fh = $msg->open('sendmail');

serves the same purpose as:

# Use sendmail for mailing $mailer = Mail::Mailer->new('sendmail)';

This code tells Mail::Send to use sendmail as the mail program.

Mail::Send also provides the set and add functions, which assign a value to a header tag and append a value to a header tag, respectively. The set function takes two arguments-a header tag and a value-and is used like this:

$msg->set($scalar, @array);

Therefore, to address a message to you@mail.somename.com:

$msg->set('To', 'you@mail.somename.com');

The above sets the To header to you@mail.somename.com; however, the following sets the To header to postmaster@mail.somename.com and you@mail.somename.com because they represent an array of values:

$msg->set('To', ('you@mail.somename.com', 'postmaster@mail.somename.com'));

You might think that you could use the set function as follows to add multiple values to a header value:

$msg->set('To', 'you@mail.somename.com'); $msg->set('To', 'someone@their.mailaddress.com');

However, set doesn't append information from one call to another, and the above example would send the mail only to someone@their.mailaddress.com. To append a name to the To header, use the add method. For example:

$msg->add('To', 'you@mail.somename.com'); $msg->add('To', 'someone@their.mailaddress.com');

The following methods are defined for Mail::Send.

$msg = new Mail::Send [header=>'value'[, ...]] 

Constructor. Creates a new Mail::Send object that is the mail message you want to send. You can include values for headers when you create the object, or include them later by calling the appropriate methods.

$msg->add(header, values) 

Adds a header to the message. header is the header to be added, and values is a list of values to be appended to that header.

$msg->bcc(values) 

Adds a Bcc header containing the mail addresses specified in the list of values to the message. If there already is a Bcc, the new values replace any old values.

$msg->cancel 

Not implemented yet, but will cancel the message.

$msg->cc(values) 

Adds a Cc header containing the mail addresses in the list of values to the message. If there already is a Cc, the new values replace any old values.

$fh->close 

Closes the filehandle $fh (which was returned by open) and sends the message.

$msg->delete(header) 

Deletes the header header from the message.

$fh = $msg->open 

Opens a filehandle for the message object. The filehandle is a Mail::Mailer object.

$msg->set(header, values) 

Sets the header header to the contents of the array values.

$msg->subject('What this message is about') 

Sets the value of the Subject field.

$msg->to(values) 

Sets the To field to the list of recipients in values.

Handle Folders with Mail::Folder

Once you've begun downloading and reading your mail from a POP server, you might want to save or categorize your messages into folders, which allow you to add, delete, save, and move messages easily. You can do this with Mail::Folder, which was written by Kevin Johnson as an object-oriented, folder-independent interface to mail folders. Mail::Folder supports a number of mailbox formats with the following interfaces:

• Mail::Folder::Emaul
• A folder interface somewhat similar to MH.
• Mail::Folder::Maildir
• An interface to maildir folders.
• Mail::Folder::Mbox
• Standard Unix mailbox format.
• Mail::Folder::NNTP
• The beginnings of an interface to NNTP. Not all the methods are implemented yet.

If you are interested in writing a folder interface, see the documentation for the module. The documentation explains the concepts and issues involved and describes some of the methods you may need to override.

The following methods are defined for Mail::Folder.

$folder = new(ftype[, foldername][, options]) 

Creates a new Mail::Folder object of the specified type. Arguments are:

• ftype
• The type of folder. Possible values are mbox, maildir, emaul, or NNTP.
• foldername
• The name of the folder. If present, the open method is called with foldername as the argument.
• options
• A hash in which the following options may be the keys:
  • Content-Length
  • Content-length header is created or updated by append_message and update_message.
  • Create
  • If set, the folder is created if it doesn't already exist.
  • DefaultFolderType
  • Autodetects folder type if create option is set and AUTODETECT has been set.
  • DotLock
  • Uses lock-style folder locking with the proper folder interface (currently used only with the mbox interface).
  • Flock
  • Uses flock-style folder locking with the proper folder interface (currently used only with the mbox interface).
  • NFSLock
  • Deals with NFS-style file locking with the proper folder interface and the NFS server in question.
  • notMUA
  • If set, makes updates but doesn't save message labels or the current message indicator. If not set (the default), saves labels and the current message indicator as appropriate for the folder interface.
  • Timeout
  • Overrides the default timeout value. Specified in seconds. Particularly useful for folder interfaces that involve network communications.

$folder->add_label(msg_num, label) 

Associates the label label with the message msg_num. Returns on success or if the label has a length of 0. Possible values of label are:

• deleted
• Used by delete_message and sync to process message deletion.
• edited
• Added by update_message to indicate that the message has been edited.
• filed, forwarded, printed, replied
• Not acted on.
• seen
• Message has been viewed by the user. Set by get_message for any message it has retrieve d.

$folder->append_message(\$mi_ref) 

Adds message to a folder. Argument is a reference to a Mail::Internet object.

$folder->clear_label(label) 

Deletes the association with label for all messages in the folder. Returns the number of messages for which there was an association.

$folder->close 

Does any necessary housekeeping and closes the folder.

$folder->current_message([msg_num]) 

With no argument, returns the message number of the current message in the folder. With an argument, sets the current message number for the folder to msg_num.

$folder->debug([value]) 

Sets the level of debugging information for the object to value. With no argument, returns the current debugging level.

$folder->debug_print(text) 

Prints text, plus some additional information, to STDERR.

$folder->delete_label(msg_num, label) 

Deletes the association of label with msg_num. Returns on success and if there was no association.

$folder->delete_message(msgs) 

Takes a list of messages, msgs, to be marked for deletion. The messages aren't actually deleted until sync is called.

$folder->dup(msg_num, \$folder_ref) 

Copies the message specified by msg_num to the folder referenced by $folder_ref. Like refile, but doesn't delete the original message. Generates a fatal error if no folder is currently open or if the folder doesn't contain message msg_num.

$folder->first_labeled_message(label) 

Returns the message number of the first message in the folder that has label associated with it, or if there are none.

$folder->first_message 

Returns the message number of the first message in the folder.

$folder->foldername 

Returns the name of the folder that the object has opened.

$folder->get_fields(msg_num, fields) 

Retrieves the fields specified in the list fields for message msg_num. If called in list context, returns a list; in scalar context, returns a reference to a list of the fields. Returns the fields in the same order as they were specified.

$folder->get_header(msg_num) 

Extracts a message header; takes one argument: the message number. Returns a reference to a Mail::Header object.

$folder->get_message(msg_num) 

Takes a message number as argument and returns a Mail::Internet object reference to that message, or on failure.

$folder->get_message_file(msg_num) 

Like get_message, but returns a filename instead of a Mail::Internet object reference.

$folder->get_mime_header(msg_num) 

Works much like get_header, but returns a reference to a MIME::Head object instead. Takes one argument, the message number.

$folder->get_mime_message (msg_num[, parserobject][, options]) 

Returns a MIME::Entity object for the specified message. Calls get_message_file to get a message to parse, creates a MIME::Parser object, and uses that to create the MIME::Entity object. The arguments are:

• msg_num
• The number of the message.
• parserobject
• If specified, used instead of internally creating a parser object.
• options
• Maps onto the equivalent MIME::Parser methods. Specified as key/value pairs, with possible values of: output_dir, output_prefix, output_to_core. See the MIME::Parser documentation for details.

$folder->get_option(option) 

Returns the setting for the specified option, or undef if the option doesn't exist.

$folder->inverse_select(\$func_ref) 

Returns a list, in no specific order, of message numbers that do not match a set of criteria. The argument, $func_ref, is a reference to a function used to determine the criteria. The function is passed a reference to a Mail::Internet object containing only a header.

$folder->is_readonly 

Returns if the folder has the readonly attribute set; otherwise, returns .

$folder->label_exists(msg_num, label) 

Returns if label is associated with message msg_num; otherwise, returns .

$folder->last_labeled_message(label) 

Returns the message number of the last message in the folder with the label label associated with it, or if there is no such message number.

$folder->last_message 

Returns the message number of the last message in the folder.

$folder->list_all_labels 

Returns a list, in no specific order, of all labels associated with messages in the folder. If called in scalar context, returns the number of labels associated with the messages.

$folder->list_labels(msg_num) 

Returns a list, in no specific order, of all labels associated with msg_num. If called in scalar context, returns the number of labels associated with the message.

$folder->message_exists(msg_num) 

Returns if a message with the number msg_num exists in the folder; otherwise, returns .

$folder->message_list 

Returns a list of the message numbers in the folder, in no specific order. The syntax is:

print $folder->message_list."\n"

$folder->next_labeled_message(msg_num, label) 

Returns the message number of the next message in the folder relative to msg_number that has the label label associated with it, or if there is no such message.

$folder->next_message([msg_num]) 

Returns the number of the next message in the folder relative to msg_numif it is specified; otherwise, relative to the current message. Returns if at end of folder.

$folder->open(foldername) 

If you didn't specify a folder name in the constructor, you need to call the open method, which takes the folder name as an argument and opens the folder. Also sets readonly if the folder is determined to be read-only.

$folder->pack 

For formats that allow message number sequences to have gaps, renames the files in the folders to eliminate any such gaps. May result in renumbering some messages.

$folder->prev_labeled_message(msg_num, label) 

Returns the message number of the previous message in the folder relative to msg_num that has the label label associated with it, or if there is no such message.

$folder->prev_message([msg_num]) 

Returns the number of the previous message in the folder relative to msg_num if it is specified; otherwise, relative to the current message. Returns if at the beginning of the folder.

$folder->qty 

Returns the number of messages in the folder. The syntax is:

print "There are ".$folder->qty." messages in your folder\n";

$folder->refile(msg_num, \$fldr_ref) 

Moves messages between folders. Takes a message number and folder reference as arguments.

$folder->select(\$func_ref) 

Returns a list of messages that meet a set of criteria. The argument, $func_ref, is a reference to a function used to determine the criteria. The function is passed a reference to a Mail::Internet object containing only a header. The list is returned in no specific order.

$folder->select_label(label) 

Returns a list of messages with the label label. If called in scalar context, returns the number of messages that have the label.

$folder->set_option(option, value) 

Sets the specified option to value.

$folder->set_readonly 

Sets the readonly attribute for the folder. Once readonly has been set, sync won't perform any updates to the actual folder.

$folder->sort(\$func_ref) 

Returns a sorted list of messages. $func_ref is a reference to a function that is passed two Mail::Header message references and returns an integer less than, equal to, or greater than 0 to indicate the sort order.

$folder->sync 

Synchronizes the folder with internal data structures and reads in any new messages since the last open or sync. Does not perform any updates if the readonly attribute has been set.

$folder->undelete_message(msgs) 

Unmarks a list of messages, msgs, that have been marked for deletion.

$folder->update_message(msg_num, \$mref) 

Replaces the message specified by msg_num with the contents of the message given by $mref, which is a reference to a Mail::Internet object.

Handle Messages with Mail::Internet

Mail::Internet implements a number of helpful functions for manipulating a mail message. These include body, print_header, and head. Mail::Internet is built on top of Mail::Header, which parses the header of an email message, and it inherits the Mail::Header constructor style that requires that a file descriptor or reference to an array be used. For example:

@lines = <STDIN>; $mi_obj = new Mail::Internet([@lines]);

reads a mail message from STDIN (using a reference to an array). The following example reads a mail message from a filehandle, FILE:

open(FILE, "/home/nvp/Mail/nvp"); $mi_obj = new Mail::Internet(\*FILE); close(FILE);

The print_header function outputs the header of a message to a file descriptor; the default is STDOUT:

open(FILE, "/home/nvp/Mail/nvp"); $mi_obj = new Mail::Internet(\*FILE); close(FILE); $mi_obj->print_header(\*STDOUT);

The above example might output:

From nvp Mon Jun 9 00:11:10 1997 Received: (from nvp@localhost) by mail.somename.com (8.8/8.8) id AAA03248 for nvp; Mon, 9 Jun 1997 00:11:09 -0500 (EST) Date: Mon, 9 Jun 1997 00:11:09 -0500 (EST) From: "Nathan V. Patwardhan" <nvp> Message-Id: <199706090511.AAA03248@mail.somename.com> To: nvp Subject: pop test X-Status: X-Uid: 1 Status: RO

in which print_body also takes a file descriptor as an argument, but outputs only the body of the message, whereas the print function outputs an entire message.

Mail::Internet Reference

$mail = new Mail::Internet ([arg], [options]) 

Creates a new Mail::Internet object. arg is optional and may be either a file descriptor (a reference to a glob) or a reference to an array. If present, the new object is initialized with headers either from the array or read from the file descriptor. options is a list of options in the form of key/value pairs. Possible options are:

• Header
• Mail::Internet should not attempt to read a mail header from arg, if it was specified. Value is a Mail::Header object.
• Body
• Mail::Internet should attempt to read the body from arg, if it was specified. Value is a reference to an array that contains the lines of the message body.
• Modify
• Reformats the headers if true. Mail::Header option.
• MailFrom
• Specifies behavior for headers in the form "From ". Mail::Header option. Possible values are:
  • IGNORE
  • Ignores and discards the headers
  • ERROR
  • Calls die
  • COERCE
  • Renames headers to Mail-From
  • KEEP
  • Keeps headers as they are
• FoldLength
• Value is default line length for folding headers. Mail::Header option.

$mail->add_signature([file]) 

Appends a signature to the message. file is a file that contains the signature; if not specified, the file $ENV{HOME}/.signature is checked for a signature.

$mail->body( ) 

Returns the body of the message as a reference to an array. Each entry in the array represents one line of the message.

$mail->escape_from( ) 

Inserts a leading > on any line that starts with "From " to avoid the problems that some applications have if a message contains a line starting with "From ".

$headobj = $mail->head( ) 

Returns the Mail::Header object that holds the headers for the current message.

$mail->nntppost([options]) 

Posts an article via NNTP; requires Net::NNTP. Options are passed as key/value pairs. Available options are:

• Debug
• Debug value to pass to Net::NNTP
• Host
• Name of NNTP server to connect to
• Port
• Port number to connect to on remote host

$mail->print_header([\*fd]) $mail->print_body([\*fd]) $mail->print([\*fd]) 

Prints the header, body, or whole message to file descriptor *fd, which should be a reference to a glob. If the file descriptor is not given, the output is sent to STDOUT:

$mail->print(\*STDOUT); # Print message to STDOUT

$mail->remove_sig([nlines]) 

Removes a user's signature from the body of a message. Looks for a line equal to "-- " within the last nlines lines of the message and removes that line and all lines after it. nlinesdefaults to .

$reply = $mail->reply( ) 

Creates a new object with headers initialized for a reply to the current object and with a body that is an indented copy of the current message.

$mail->smtpsend( ) 

Sends the Mail::Internet message via SMTP to all addresses on the To, Cc, and Bcc lines. Finds the SMTP host by trying to connect first to hosts specified in $ENV{SMTPHOSTS}, then to mailhost, and then to localhost.

In a future release of Mail::Internet, smtpsend will be able to take the hostname as a parameter, as nntppost does.

$mail->tidy_body( ) 

Removes all leading and trailing lines that contain only whitespace from the message body.

$mail->unescape_from( ) 

Removes the escaping added by escape_from.

Parse Email Addresses with Mail::Address

Mail::Address parses RFC 822-compliant mail addresses of the form:

"Full Name or Phrase" <username@host> (Comment Area)

For example, under RFC 822, an address might be represented as:

"Nathan V. Patwardhan" <nvp@mail.somename.com> (No Comment)

or:

"Nathan V. Patwardhan" <nvp@mail.somename.com>

The Mail::Address constructor parses an email address into three parts based on the categories shown above:

$addr = Mail::Address->new("Full Name or Phrase", "username@host", "(Comment Area)");

Mail::Address also outputs portions of the mail address with the functions phrase, address, comment, format, name, host, and user. The phrase, address, and comment functions represent the first, second, and third entities that were passed to the Mail::Address constructor, in which the phrase function:

print $addr->phrase( );

outputs:

Nathan V. Patwardhan

the address function:

print $addr->address( );

outputs:

nvp@mail.somename.com

and the comment function:

print $addr->comment( );

outputs:

No Comment

A real mail address can be "unmangled," or parsed from its user@somehost.com format, with the user and host functions. The user function removes everything starting with the @ to the end of the address, and host removes everything up to and including the @. Using the previous example of nvp@mail.somename.com, the following line:

print $addr->user;

outputs:

nvp

And the following line using the host function:

print $addr->host;

outputs:

nvp@mail.somename.com

Mail::Address Reference

$addr = Mail::Address->new(phrase, address[, comment]) 

Constructor. Creates new Mail::Address object representing an address with the specified elements. In a message, these three elements show up as:

phrase <address> (comment) address (comment)

Mail::Address->parse(line) 

Constructor. Parses the specified line, usually a To, Cc, or Bcc line, and returns a list of extracted Mail::Address objects.

$addr->address( ) 

Returns the address part of the object.

$addr->canon( ) 

Unimplemented, but should return the UUCP canon for the message.

$addr->comment( ) 

Returns the comment part of the object.

$addr->format( ) 

Returns a string representing the address in a form suitable for the To, Cc, or Bcc line of a message

$addr->host( ) 

Returns the host portion of the address.

$addr->name( ) 

Takes information contained in the object and uses various heuristics to try to identify the name of the person or group.

$addr->path( ) 

Unimplemented, but should return the UUCP path for the message.

$addr->phrase( ) 

Returns the phrase part of the object.

$addr->user( ) 

Returns the user ID portion of the address.

Checking Blacklisted Hosts with Mail::RBL

Mail::RBL eases the task of checking if a given host is in the real-time blackhole list. Mail::RBL does this by speaking directly to the RBL server and searching for a specified host. Ordinarily, you build this functionality into your MTA (sendmail, qmail, Exim, etc.), but if your system administrator hasn't built RBL support into your MTA, you might consider integrating Mail::RBL into your own mail filter.

• new(suffix)
• Creates a list handle. suffix is required because it denotes the host from which you'll check hostnames.
• check($host)
• Performs the lookup against the RBL. $host can be a hostname or IP address, without trailing netmasks (represented by a / followed by an octet).

  For example:

  use Mail::RBL; my $host = q[some-spammer.domain.here]; my $rbl = Mail::RBL->new('list.org'); if($rbl->check($host)) {
   print "$host is in the RBL, and I won't deliver the mail."
  }
  else {
   # Do something to deliver the email }
  

Mail Filtering with Mail::Audit

Mail::Audit is a mail-filtering system for those who want to write good filter rules but choose not to use procmail. It was written to provide flexibility while realizing the strengths of Perl's regular expression engine. Inspired by Tom Christiansen's audit_mail and deliverdb programs, Mail::Audit allows an email message to be logged, examined, routed to another folder or INBOX, resent, or rejected. You should be able to write a simple ruleset or rulesets and put references to it in your forward file. For example:

use Mail::Audit; my $m_au = Mail::Audit->new( ); $m_au->reject("Let me call YOU at home!") if $m_au =~ /(spammer\@spammer.com|spammer2\@spammer2.com|spammer3\@spammer3.com)/; $m_au->accept("Majordomo") if $mail->from =~ /Majordomo\@/; $m_au->accept( );

Mail::Audit implements the following methods.

new(%options) 

Constructor. Reads a mail message from STDIN (or, if the data option is set, from an array reference) and creates a Mail::Audit object from it. Options include:

• log=>logfile
• Writes a debugging log.
• loglevel=>n
• Sets verbosity of the log on a scale of 1 to 4.
• noexit=>1
• Do not exit after delivering mail.

If you specify a log level without a log file, logging will be written to /tmp/username-audit.log, where username is replaced by your username.

body( ) 

Returns a reference to an array of lines in the body of the email.

get(header) 

Retrieves the named header from the mail message.

header( ) 

Returns the header as a single string.

ignore( ) 

Ignores an email message completely, dumping it into the bit bucket.

pipe(program) 

Opens a pipe to an external program and feeds the message to it.

put(header, value) 

Inserts a new header into the mail message with the given value.

reject(message) 

Rejects an email message, then notifies the sender that the message is undeliverable with message as the reason given.

resend(address) 

Bounces the email in its entirety to another address.

tidy( ) 

Tidies up the email as per the Mail::Internet manpage.

xaccept(filename) 

Writes the incoming (and filtered) mail into a mailbox at filename. If filename is undefined, mail is written to /var/spool/mail/$USER. If you use Maildir instead of mbox-formatted mail, it will deliver the mail in Maildir style.

Alias Manipulation with Unix::AliasFile

While not a member of the Mail umbrella, Unix::AliasFile is an important module since it implements a complete interface to the Unix aliases text file that allows you to query, add, update, and delete aliases. In addition, it has a cleaner interface than Mail::Alias. Unix::AliasFile automatically handles file locking, comma and colon placement, and any other detail that's related to manipulating your Unix mail alias file. For example:

use Unix::AliasFile; my $aliasfile = '/etc/mail/aliases'; my $uaf = Unix::AliasFile->new($aliasfile); foreach my $alias $uaf->aliases( ) {
 chomp($alias); if($uaf->alias($alias) ne "$alias\@yourpopserver.your.domain") {
 # Doesn't exist, so add alias of the form: # alias: alias@yourpopserver.your.domain $uaf->alias($alias, ("$alias\@yourpopserver.your.domain"));
}
else {
 print "I already have $alias that way.\n";
}
} $uaf->commit( ); undef $uaf;

Unix::AliasFile implements the following methods.

new(filename) 

Constructor. Creates a new Unix::AliasFile object.

add_user(alias, @users) 

Adds @users to alias. If a user in @users already exists in alias, duplicates will be ignored. If alias is set to *, @users will be added to every alias.

alias(alias, @users) 

Adds, modifies, or returns information about an alias. When only alias is suppled, alias( ) returns a list of all members of an alias, or undef if alias does not exist. If you supply @users, alias will be modified or created if it doesn't already exist.

aliases( ) 

Returns an alphabetized list of all existing aliases. In scalar context, this method returns the total number of aliases.

comment(alias, comment) 

Inserts a comment line before alias. comment must begin with #, but a newline will be appended to it. Returns on success and on failure.

commit( ) 

Writes the alias file.

delempty( ) 

Deletes all existing aliases that have no members, returning a count of the number of aliases deleted.

delete(alias) 

Deletes alias.

remove_user(alias, @users) 

Removes the list of users from an existing alias. If a user in @usersisn't a member of alias, the removal attempt will be silently ignored. remove_user( ) returns on success and on failure.

rename_user(oldname, newname) 

Changes one username to another in every alias. Returns the number of aliases affected.

uncomment(comment) 

Removes the comment from the file that is exactly matched to the supplied text. Returns on success and on failure.