INTRODUCTION This is the README file for the PERL module Mail::Alias for Version 1.15 26 February 2022 Mail::Alias is avaiable for download at www.CPAN.org under Mail modules or under the CPAN author ID: JIK. Source code is available at https://github.com/jikamens/Mail-Alias. You require perl 5.001 or later to use this library This is a legacy of the previous version of Mail::Alias that was included in MailTools. This module may actually work with earlier versions of PERL All files contained in this installation are Copyright (c) 2022 Jonathan Kamens. All rights reserved. This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself. Copyright (c) 2022 Jonathan Kamens . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Portions of earlier versions of this program were copyrighted by Tom Zeltwanger and Graham Barr. The current copyright holder extends full authorship rights to both of the previous authors. Note: There is brief Mail::Alias documentation embedded in the Mail::Alias module, which can be accessed by typing "man Mail::Alias" after installation or by typing "perldoc Alias.pm" in the directory containing Alias.pm ----------------------------------------------------------------------------- Any questions or comments (Please send your feeback) should be addressed to - Jonathan Kamens - ----------------------------------------------------------------------------- INSTALLATION To install the library, run these commands: perl Makefile.PL make make test make install After installation, you should be able to see the brief documentation by typing "man Mail::Alias" You will now be able to access the Mail::Alias methods by adding "use Mail::Alias" to the beginning of your PERL program. SYNOPSYS This module allows direct manipulation of various types of E-Mail Alias files. The primary use of Mail::Alias is for manipulating alias files in the SENDMAIL alias file format. Additionally it is possible to read some other formats and to convert between various alias file formats. HISTORY From Jonathan Kamens in 2022: I took over maintenance of this module in 2022 to fix a breaking incompatibility with the current version of Perl going back several years. To date no changes have been made to the module except that one fix. From Tom Zeltwanger in 2000: The capabilities provided in this module were developed as part of the development of a now-defunct E-mail Forwarding service. The service was based on SENDMAIL and used PERL for automatic processing of Alias files. This code has been provided to the PERL community in appreciation for the free PERL software and the incredible support network that comes with PERL at no charge. This module also incorporates Alias code from the MailTools module written by Graham Barr. My appreciation to Graham for that work, and for letting me combine our works, and assume authorship of Mail::Alias. DESCRIPTION MODULE OVERVIEW Mail::Alias allows you to directly access the contents of E-Mail alias files. You can perform the following actions: Set the name of the current aliases file being accessed Verify the presence of aliases Retrieve an alias line from the file Add aliases Change the addresses for aliases Delete aliases Direct access of the files has a small price. When files are being manipulated directly, operations are somewhat slower than they would be if the entire alias file contents was brought into memory first. However, this provides the most flexibility, and does not disrupt the ordering of the file, or any comments in the file. This delay factor will not be a problem unless you have huge alias files. After you make changes, don't forget you will need to rebuild the active alias database (for SENDMAIL this is done by executing the NEWALIASES command). For backward compatibility with earlier versions of Mail::Alias, there is a separate set of indirect access methods. These provide 100 percent interface-level compatibility with prior versions (versions before 1.10). The indirect methods act on files by reading them into memory first. This mode of operation will be referred to as MEMORY mode, while the normal mode of operating directly on the files will be referred to as the FILE mode. With the MEMORY mode, you can perform the following operations: Read alias file contents into memory Define the alias file format Write alias data in memory to a new file Expand an alias into its delivery addresses Verify the existance of an alias in memory When possible, it is recommended that you use the FILE method for accessing your alias files. Future versions will concentrate on expanding the capabilities in FILE mode. Methods are also provided to make it easy to switch between FILE and MEMORY modes. If you are mainly interested in expansion of aliases for sending messages, MEMORY mode has a strong expansion method that properly handles recursion and :include: files. My descriptions of aliases and alias files will be obviously biased toward SENDMAIL, as it is the Mail Transport Agent (MTA) which with I am most familiar. I welcome comments from experts with non-SENDMAIL environments that will help to make this module as universally useful as possible. Most of the methods have been written specifically for manipulating SENDMAIL alias files. INTERFACE The interface is Object Oriented, so familiarity with OO PERL is requried. Using a PERL OO module is very easy, and is well described in several books. To use the module you must first add the line "use Mail::Alias" in your code. Nest, you will create an Alias object using the standard new() constructor method. After you have created the object, you use method calls that pass a reference to a hash (e.g. $my_object->exists("some_alias")). You can not use functional-style calls to the Mail::Alias methods because the names are not exported, and they all expect that the name of the object class will be passed as the first argument. METHODS The operation of each method is described briefly below. Usage syntax is shown in the embedded documentation in Alias.pm which is also found in the man page. As mentioned earlier, most of the methods are specific to either the FILE mode or the MEMORY mode. Please note that a few methods are used in both modes. To help make the method usage easier to understand, there are several test scripts in the testscripts directory that should help to explain the usage. FILE MODE METHODS Objects that are created for FILE mode access must be in SENDMAIL format. If you have an alias file in another format, you may first use the MEMORY modes to define the file format, read the alias file data, change to Sendmail format, and write the file in the Sendmail format. - Creates an Alias object using the specified filename The class name should be specified only as Mail::Alias If no filenam is passed, it uses the standard SENDMAIL alias file: /etc/mail/aliases - Indicates the presence of the passed alias in the current aliases file and returns the entire line from the file it the alias is found. The returned line will be in the form [alias: address_string] where the address_string is comprised of one, or more E-Mail addresses or aliases also in the file. If the alias is not found in the file, exists() returns an undefined value. - Sets or gets the name of the current alias filename for direct access. - Sets the working mode to MEMORY. Methods specific to the MEMORY mode are read(), write() and format() methods. MEMORY MODE METHODS - Creates an Alias module using a specified format The class for creating objects ofr MEMORY mode access must include the file format (e.g. Mail::Alias::Sendmail). Reads an alias file of the specified format into memory. Comments or blank lines are lost upon reading. Due to storage in a hash, ordering of the alias lines is also lost. - The current set of aliases contained in the object memory is written to a file using the current format. If a filehandle is passed, data is written to the already opened file. If a filename is passed, it is opened and the memory is written to the file. Note: if passing a filename, include the mode (i.e. to write to a file named aliases pass >aliases). Before writing, the alias lines are sorted alphabetically. - Indicates the presence of the passed alias within the object after a file has been read. - Expands the passed alias into a list of addresses. Expansion properly handles :include: files, recursion, and continuation lines. If the alias is not found in the object, you get back what you sent. Set the current alias file format. Currently available formats include Sendmail, Binmail, and Ucbmail. Each format has read and write methods. - Sets the working mode to FILE. Methods specific to the FILE mode are append() and delete() methods.