This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Mac/Macbinary, Next: Mac/OSA/Simple, Prev: Mac/Glue, Up: Module List Decodes Macbinary files *********************** NAME ==== Mac::Macbinary - Decodes Macbinary files SYNOPSIS ======== use Mac::Macbinary; $mb = Mac::Macbinary->new(\*FH); # filehandle $mb = Mac::Macbinary->new($fh); # IO::* instance $mb = Mac::Macbinary->new("/path/to/file"); # do validation eval { $mb = Mac::Macbinary->new("/path/to/file", { validate => 1 }); }; $header = $mb->header; # Mac::Macbinary::Header instance $name = $header->name; DESCRIPTION =========== This module provides an object-oriented way to extract various kinds of information from Macintosh Macbinary files. METHODS ======= Following methods are available. Class method ------------ new( THINGY, [ \%attr ] ) Constructor of Mac::Macbinary. Accepts filhandle GLOB reference, FileHandle instance, IO::* instance, or whatever objects that can do read methods. If the argument belongs none of those above, new() treats it as a path to file. Any of following examples are valid constructors. open FH, "path/to/file"; $mb = Mac::Macbinary->new(\*FH); $fh = FileHandle->new("path/to/file"); $mb = Mac::Macbinary->new($fh); $io = IO::File->new("path/to/file"); $mb = Mac::Macbinary->new($io); $mb = Mac::Macbinary->new("path/to/file"); new() throws an exception "Can't read blahblah" if the given argument to the constructor is neither a valid filehandle nor an existing file. The optional "\%attr" parameter can be used for validation of file format. You can check and see if a file is really a Macbinary or not by setting "validate" attribute to 1. $fh = FileHandle->new("path/to/file"); eval { $mb = Mac::Macbinary->new(FileHandle->new($fh), { validate => 1, }); }; if ($@) { warn "file is not a Macbinary."; } Instance Method --------------- data returns the data range of original file. header returns the header object (instance of Mac::Macbinary::Header). Following accessors are available via Mac::Macbinary::Header instance. name, type, creator, flags, location, dflen, rflen, cdate, mdate returns the original entry in the header of Macbinary file. Below is a structure of the info file, taken from MacBin.C char zero1; char nlen; char name[63]; char type[4]; 65 0101 char creator[4]; 69 char flags; 73 char zero2; 74 0112 char location[6]; 80 char protected; 81 0121 char zero3; 82 0122 char dflen[4]; char rflen[4]; char cdate[4]; char mdate[4]; EXAMPLE ======= Some versions of MSIE for Macintosh sends their local files as Macbinary format via forms. You can decode them in a following way: use CGI; use Mac::Macbinary; $q = new CGI; $filename = $q->param('uploaded_file'); $type = $q->uploadInfo($filename)->{'Content-Type'}; if ($type eq 'application/x-macbinary') { $mb = Mac::Macbinary->new($q->upload('uploaded_file')); # now, you can get data via $mb->data; } COPYRIGHT ========= Copyright 2000 Tatsuhiko Miyagawa This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ACKNOWLEDGEMENT =============== Macbinary.pm is originally written by Dan Kogai . There are also `Mac::Conversions' and `Convert::BinHex', working kind similar to this module. (However, `Mac::Conversions' works only on MacPerl, and `Convert::BinHex' is now deprecated.) Many thanks to Paul J. Schinder and Eryq, authors of those ones. Macbinary validation is almost a replication of *is_macbinary* in Mac::Conversions. SEE ALSO ======== perl(1), `Mac::Conversions' in this node, *Note Convert/BinHex: Convert/BinHex,.  File: pm.info, Node: Mac/OSA/Simple, Next: Mac/RecentDocuments, Prev: Mac/Macbinary, Up: Module List Simple access to Mac::OSA ************************* NAME ==== Mac::OSA::Simple - Simple access to Mac::OSA SYNOPSIS ======== #!perl -wl use Mac::OSA::Simple; osa_script('LAND', <<'EOS'); dialog.getInt ("Duration?",@examples.duration); dialog.getInt ("Amplitude?",@examples.amplitude); dialog.getInt ("Frequency?",@examples.frequency); speaker.sound (examples.duration, examples.amplitude, examples.frequency) EOS print frontier('clock.now()'); applescript('beep 3'); DESCRIPTION =========== **MAJOR CHANGE** Scripting component in osa_script and compile_osa_script is now the first parameter, not the second. Now the script text is second. You can access scripting components via the tied hash `%ScriptComponents' which is automatically exported. Components are only opened if they have not been already, and are closed when the program exits. It is normally not necessary to use this hash, as it is accessed internally when needed. Also usually not necessary, but possibly useful, are all the functions and constants from Mac::OSA, available with the EXPORT_TAG "all". Functions --------- The following functions are automatically exported. osa_script(SCRIPTCOMPONENT, SCRIPTTEXT) Compiles and executes SCRIPTTEXT, using four-char SCRIPTCOMPONENT. Component is opened and closed behind the scenes, and SCRIPTTEXT is compiled, executed, and disposed of behind the scenes. If the script returns data, the function returns the data, else it returns 1 or undef on failure. applescript(SCRIPTTEXT) frontier(SCRIPTTEXT) Same thing as `osa_script' with SCRIPTCOMPONENT already set ('ascr' for AppleScript, 'LAND' for Frontier). compile_osa_script(SCRIPTCOMPONENT, SCRIPTTEXT) Compiles script as `osa_script' above, but does not execute it. Returns Mac::OSA::Simple object. See `"Methods"' in this node for more information. compile_applescript(SCRIPTTEXT) compile_frontier(SCRIPTTEXT) Same thing as `compile_osa_script' with SCRIPTCOMPONENT already set. load_osa_script(HANDLE) load_osa_script(FILE, FROMFILE [, RESOURCEID]) In the first form, load compiled OSA script using data in HANDLE (same data as returned by compiled method; see `Mac::Memory' in this node). In the second form, with FROMFILE true, gets script from FILE using RESOURCEID (which is 128 by default). Returns Mac::OSA::Simple object. **NOTE** This function uses FSpOpenResFile, which has a bug in it that causes it to treat $ENV{MACPERL} as the current directory. For safety, always pass FILE as an absolute path, for now. Example: use Mac::OSA::Simple qw(:all); use Mac::Resources; $res = FSpOpenResFile($file, 0) or die $^E; $scpt = Get1Resource(kOSAScriptResourceType, 128) or die $^E; $osa = load_osa_script($scpt); $osa->execute; CloseResFile($res); Same thing: use Mac::OSA::Simple; $osa = load_osa_script($file, 1); $osa->execute; Another example: use Mac::OSA::Simple; $osa1 = compile_applescript('return "foo"'); print $osa1->execute; # make copy of script in $osa1 and execute it $osa2 = load_osa_script($osa1->compiled); print $osa2->execute; See `"Methods"' in this node for more information. Methods ------- This section describes methods for use on objects returned by `compile_osa_script' and its related functions and `load_osa_script'. compiled Returns a HANDLE containing the raw compiled form of the script (see `Mac::Memory' in this node). dispose Disposes of OSA script. Done automatically if not called explicitly. execute Executes script. Can be executed more than once. save(FILE [, ID [, NAME]]) Saves script in FILE with ID and NAME. ID defaults to 128, NAME defaults to "MacPerl Script". DANGEROUS! Will overwrite existing resource! **NOTE** This function uses FSpOpenResFile, which has a bug in it that causes it to treat $ENV{MACPERL} as the current directory. For safety, always pass FILE as an absolute path, for now. BUGS ==== `load_osa_script' function and save method require absolute paths. Problem in Mac::Resources itself. TODO ==== Work on error handling. We don't want to die when a toolbox function fails. We'd rather return undef and have the user check $^E. Should `frontier' and/or `osa_script('LAND', $script)' launch Frontier if it is not running? Add `run_osa_script', which could take script data in a Handle or a path to a script (as with `load_osa_script'. Should save have optional parameter for overwriting resource? Should `run_osa_script' and execute take arguments? If so, how? HISTORY ======= v0.51, Saturday, March 20, 1999 Fixed silly bug in return from execute, where multiline return values would not return (added /s so . would match \n) (John Moreno ). v0.50, Friday, March 12, 1999 Changed around the argument order for `osa_script' and `compile_osa_script'. Added `load_osa_script' function. Added save method. Added lots of tests. v0.10, Tuesday, March 9, 1999 Added lots of stuff to get compiled script data. v0.02, May 19, 1998 Here goes ... AUTHOR ====== Chris Nandor `' http://pudge.net/ Copyright (c) 1999 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Please see the Perl Artistic License. SEE ALSO ======== Mac::OSA, Mac::AppleEvents, Mac::AppleEvents::Simple, macperlcat. VERSION ======= Version 0.51 (Saturday, March 20, 1999)  File: pm.info, Node: Mac/RecentDocuments, Next: Mail/Address, Prev: Mac/OSA/Simple, Up: Module List add items to the MacOS Recent Documents menu ******************************************** NAME ==== Mac::RecentDocuments - add items to the MacOS Recent Documents menu SYNOPSIS ======== use Mac::RecentDocuments qw(:ARGV); # Adds all files in @ARGV to Recent Documents folder, # and imports recent_documents and recent_document foreach my $in (@ARGV) { open(IN, "<$in") or die "Can't read-open $in: $!"; my $out = $in . '2'; die "But $out already exists!" if -e $out; open(OUT, ">$out") or die "Can't write-open $out: $!"; ...do whatever to $out... recent_documents($out); # add to Recent Documents folder } DESCRIPTION =========== This module provides a function that adds specified files to the MacOS Apple Menu "Recent Documents" folder. You can use this module under non-MacOS environments, and it will compile, but it will do nothing. FUNCTIONS ========= recent_documents( ...files... ) This adds the given items to the Recent Documents folder, for each item that is a pathspec to an existing file. Relative (`":bar.txt"') as well as absolute filespecs (`"Lame Drive:stuff:bar.txt"') should work equally well. The number of aliases that this creates in the Recent Documents folder is returned. Under non-MacOS environments, this function does nothing at all, and always returns 0. recent_document( file ) This is just an alias to `recent_documents' Mac::RecentDocuments::OK() This function returns true iff you are running under MacOS, and if, at compile-time, Mac::RecentDocuments was able to find your Recent Documents folder, and verified that it was a writeable directory. In all other cases, this returns false. IMPORTING, AND :ARGV ==================== If you say use Mac::RecentDocuments; then this will by default import the functions `recent_documents' and `recent_document'. This is equivalent to: use Mac::RecentDocuments qw(:all); If you want to use the module but import no functions, you can say: use Mac::RecentDocuments (); or use Mac::RecentDocuments qw(:none); This module also defines a use-option `":ARGV"' that causes Mac::RecentDocuments to also call `recent_documents(@ARGV)', at compile time. This should be rather useful with MacPerl droplets. That is, this: use Mac::RecentDocuments qw(:ARGV); is basically equivalent to: BEGIN { use Mac::RecentDocuments; Mac::RecentDocuments(@ARGV); } (The only difference is that if several instances of `use Mac::RecentDocuments qw(:ARGV)' are seen in a given session, `Mac::RecentDocuments(@ARGV)' is called only the first time.) When "qw(:ARGV)" is the whole option list, it is interpreted as equivalent to "qw(:ARGV :all)". If you want the `:ARGV' option without importing anything, explicitly specify the `":none"' option: use Mac::RecentDocuments qw(:ARGV :none); CAVEATS ======= The module is called Mac::RecentDocuments (no underscore), but the function is called `recent_documents' (with underscore). The module is called Mac::RecentDocuments, not Mac::RecentFiles. THANKS ====== Thanks to Chris Nandor for the `kRecentDocumentsFolderType' tips. COPYRIGHT ========= Copyright (c) 2000 Sean M. Burke. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR ====== Sean M. Burke `sburke@cpan.org'  File: pm.info, Node: Mail/Address, Next: Mail/Alias, Prev: Mac/RecentDocuments, Up: Module List Parse mail addresses ******************** NAME ==== Mail::Address - Parse mail addresses SYNOPSIS ======== use Mail::Address; my @addrs = Mail::Address->parse($line); foreach $addr (@addrs) { print $addr->format,"\n"; } DESCRIPTION =========== `Mail::Address' extracts and manipulates RFC822 compilant email addresses. As well as being able to create `Mail::Address' objects in the normal manner, `Mail::Address' can extract addresses from the To and Cc lines found in an email message. CONSTRUCTORS ============ new( PHRASE, ADDRESS, [ COMMENT ]) Mail::Address->new("Perl5 Porters", "perl5-porters@africa.nicoh.com"); Create a new `Mail::Address' object which represents an address with the elements given. In a message these 3 elements would be seen like: PHRASE
(COMMENT) ADDRESS (COMMENT) parse( LINE ) Mail::Address->parse($line); Parse the given line a return a list of extracted `Mail::Address' objects. The line would normally be one taken from a To,Cc or Bcc line in a message METHODS ======= phrase () Return the phrase part of the object. address () Return the address part of the object. comment () Return the comment part of the object format () Return a string representing the address in a suitable form to be placed on a To,Cc or Bcc line of a message name () Using the information contained within the object attempt to identify what the person or groups name is host () Return the address excluding the user id and '@' user () Return the address excluding the '@' and the mail domain path () Unimplemented yet but should return the UUCP path for the message canon () Unimplemented yet but should return the UUCP canon for the message AUTHOR ====== Graham Barr COPYRIGHT ========= Copyright (c) 1995-8 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Mail/Alias, Next: Mail/Audit, Prev: Mail/Address, Up: Module List Maniulates mail alias files of various formats. Works on files directly or loads files into memory and works on the buffer. *************************************************************************************************************************** NAME ==== Mail::Alias - Maniulates mail alias files of various formats. Works on files directly or loads files into memory and works on the buffer. SYNOPSIS ======== use Mail::Alias; DESCRIPTION =========== `Mail::Alias' can read various formats of mail alias. Once an object has been created it can be used to expand aliases and output in another format. CONSTRUCTOR =========== new () Alias objects can be created in two ways; With a format specified- Mail::Alias::Sendmail->new([filename]) Without a format specified- Mail::Alias->new([filename]}. Format defaults to SENDMAIL In either case, the filename is optional and, if supplied, it will be read in when the object is created. Available formats are Sendmail, Ucbmail, and Binmail. METHODS ======= *read ()* 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. *write ()* The current set of aliases contained in the object memory are 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. *format ()* Set the current alias file format. *exists ()* Indicates the presence of the passed alias within the object (if using memory access), or the current aliases file (if using direct file access). For direct file access, the return value is the address string for the alias. =item *expand ()* Expands the passed alias into a list of addresses. Expansion properly handles :include: files, recursion, and continuation lines.Only works when memory access is being used. If the alias is not found in the object, you get back what you sent. *alias_file ()* Sets or gets the name of the current alias filename for direct access. *append () *-Sendmail only-** Adds an alias to an existing Sendmail alias file. The alias and addresses can be passed as two separate arguments (alias, addresses) or as a single line of text (alias: addresses) *delete () *-Sendmail only-** Deletes the entry for an alias from the current alias file. *update () *-Sendmail only-** Replaces the address string entry for an alias in the current alias file. *usemem ()* Sets the working mode to use memory (indirect access). Use read(), write() and format() methods. *usefile ()* Sets the working mode to use files (direct access). Use append() and delete() methods. AUTHOR ====== Tom Zeltwanger (CPAN author ID: ZELT) COPYRIGHT ========= Copyright (c) 2000 Tom Zeltwanger. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Versions up to 1.06, Copyright (c) 1995-1997 Graham Barr. All rights reserved. This program is free software; you can distribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Mail/Audit, Next: Mail/Audit/KillDups, Prev: Mail/Alias, Up: Module List Library for creating easy mail filters ************************************** NAME ==== Mail::Audit - Library for creating easy mail filters SYNOPSIS ======== use Mail::Audit; # use Mail::Audit qw(...plugins...); my $mail = Mail::Audit->new; $mail->pipe("listgate p5p") if ($mail->from =~ /perl5-porters/); $mail->accept("perl) if ($mail->from =~ /perl/); $mail->reject("We do not accept spam") if looks_like_spam($mail); $mail->ignore if $mail->subject =~ /boring/i; ... DESCRIPTION =========== `procmail' is nasty. It has a tortuous and complicated recipe format, and I don't like it. I wanted something flexible whereby I could filter my mail using Perl tests. `Mail::Audit' was inspired by Tom Christiansen's `audit_mail' and `deliverlib' programs. It allows a piece of email to be logged, examined, accepted into a mailbox, filtered, resent elsewhere, rejected, and so on. It's designed to allow you to easily create filter programs to stick in a `.forward' file or similar. CONSTRUCTOR ----------- `new(%options)' The 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, to be manipulated by the following methods. Other options include the accept, `reject' or pipe keys, which specify subroutine references to override the methods with those names. You may also specify `< log =' $logfile >> to write a debugging log; you can set the verbosity of the log with the `loglevel' key, on a scale of 1 to 4. If you specify a log level without a log file, logging will be written to `/tmp/you-audit.log' where `you' is replaced by your user name. If you specify `< noexit =' 1 >>, `Mail::Audit' will not exit after delivering the mail, but continue running your filter. METHODS ------- `accept($where)' You can choose to accept the mail into a mailbox by calling the accept method; with no argument, this accepts to `/var/spool/mail/you'. The mailbox is opened append-write, then locked `LOCK_EX', the mail written and then the mailbox unlocked and closed. If Mail::Audit sees that you have a maildir style system, where `/var/spool/mail/you' is a directory, it'll deliver in maildir style. If this isn't how you want local delivery to happen, you'll need to override this method. `reject($reason)' This rejects the email; it will be bounced back to the sender as undeliverable. If a reason is given, this will be included in the bounce. `ignore' This merely ignores the email, dropping it into the bit bucket for eternity. `rblcheck([$timeout])' Attempts to check the mail headers with the Relay Blackhole List. Returns false if the headers check out fine or the query times out, returns a reason if the mail is considered spam. `pipe($program)' This opens a pipe to an external program and feeds the mail to it. `tidy' Tidies up the email as per *Note Mail/Internet: Mail/Internet, `get($header)' Retrieves the named header from the mail message. `put($header, $value') Inserts a new header into the mail message with the given value. body Returns an array of lines in the body of the email. header Returns the header as a single string. `resend($address)' Bounces the email in its entirety to another address. ATTRIBUTES ---------- The following attributes correspond to fields in the mail: * from * to * subject * cc * bcc BUGS ==== Fewer than before. AUTHOR ====== Simon Cozens SEE ALSO ======== *Note Mail/Internet: Mail/Internet,, `Mail::SMTP' in this node  File: pm.info, Node: Mail/Audit/KillDups, Next: Mail/Audit/MAPS, Prev: Mail/Audit, Up: Module List Mail::Audit plugin for duplicate suppression ******************************************** NAME ==== Mail::Audit::KillDups - Mail::Audit plugin for duplicate suppression SYNOPSIS ======== use Mail::Audit qw(KillDups); $Mail::Audit::KillDups::dupfile = "/home/simon/.msgid-cache"; my $mail = Mail::Audit->new; $mail->killdups; DESCRIPTION =========== This is a Mail::Audit plugin which provides a method for checking and supressing duplicate messages; that is, mails with message-ids which have been previously seen. METHODS ------- `killdups' Checks the incoming message against a file of previously seen message ids, ignores it if it's already seen, and adds it if it hasn't been. `$Mail::Audit::KillDups::dupfile' contains the name of the file used; if you don't set this, it will be `.msgid-cache' in the current directory. (Probably your home directory.) AUTHOR ====== Simon Cozens SEE ALSO ======== *Note Mail/Audit: Mail/Audit,  File: pm.info, Node: Mail/Audit/MAPS, Next: Mail/Audit/PGP, Prev: Mail/Audit/KillDups, Up: Module List Mail::Audit plugin for RBL checking *********************************** NAME ==== Mail::Audit::MAPS - Mail::Audit plugin for RBL checking SYNOPSIS ======== use Mail::Audit qw(MAPS); my $mail = Mail::Audit->new; ... if ($mail->rblcheck) { ... } DESCRIPTION =========== This is a Mail::Audit plugin which provides a method for checking messages against the Relay Black List. METHODS ------- `rblcheck([$timeout])' Attempts to check the mail headers with the Relay Blackhole List. Returns false if the headers check out fine or the query times out, returns a reason if the mail is considered spam. AUTHOR ====== Simon Cozens SEE ALSO ======== *Note Mail/Audit: Mail/Audit,  File: pm.info, Node: Mail/Audit/PGP, Next: Mail/Box, Prev: Mail/Audit/MAPS, Up: Module List Mail::Audit plugin for PGP header fixing **************************************** NAME ==== Mail::Audit::PGP - Mail::Audit plugin for PGP header fixing SYNOPSIS ======== use Mail::Audit qw(PGP); my $mail = Mail::Audit->new; ... $mail->fix_pgp_headers; DESCRIPTION =========== This is a Mail::Audit plugin which provides a method for checking whether a given email contains a PGP-signed or -encrypted message, and if so, adds the relevant headers to tell the mailer to check the signature or decrypt it. AUTHOR ====== Simon Cozens SEE ALSO ======== *Note Mail/Audit: Mail/Audit,  File: pm.info, Node: Mail/Box, Next: Mail/Box/Index, Prev: Mail/Audit/PGP, Up: Module List Manage a message-folder. ************************ NAME ==== Mail::Box - Manage a message-folder. SYNOPSIS ======== use Mail::Box; my $folder = new Mail::Box::Mbox file => $ENV{MAIL}, ...; print $folder->message(0)->subject; # See Mail::Box::Message $folder->message(3)->deleted(1); my $emails = $folder->messages; # amount $folder->addMessage(new Mail::Box::Message(...)); foreach (@{$folder->messages}) {...} # the messages foreach (@$folder) {...} # same Tied-interface: use Mail::Box; tie my @inbox, 'Mail::Box', file => $ENV{MAIL}; # See Mail::Box::Tied DESCRIPTION =========== Read Mail::Box::Manager first. Mail::Box is the base-class for accessing various types of mail-folder organizational structures in a uniformal way. This class extends: * Mail::Box::Threads implements thread detection and simplified access to the threads found. * Mail::Box::Locker implements various locking algorithms * Mail::Box::Tie provides simple array-based access to the folder. You need to read their manual-pages too, to find-out what a folder is capable of. The various folder-types do vary on how they store their messages (a folder with many messages in a single file or a folder as a directory with each message in a single file) Furthermore, different types of folders have different ways to be locked. Applications usually add information to the messages in the folders, for instance whether you have replied to a message or not. The base-class for messages in a folder is Mail::Box::Message (an extention of MIME::Entity). It presents message-facts in an application-independent way. Each application needs to extend Mail::Box::Message with their own practices. METHODS ======= new ARGS (Class method) Open a new folder. The ARGS is a list of labeled parameters defining what to do. Each sub-class of Mail::Box will add different options to this method. See their manual-pages. All possible options are: (for detail description of the Mail::Box specific options see below, for the other options their respective manual-pages) access Mail::Box 'r' create Mail::Box 0 dummy_type Mail::Box::Threads 'Mail::Box::Message::Dummy' folder Mail::Box $ENV{MAIL} folderdir Mail::Box lazy_extract Mail::Box 10kb lockfile Mail::Box::Locker foldername.'.lock' lock_method Mail::Box::Locker 'dotlock' lock_timeout Mail::Box::Locker 1 hour lock_wait Mail::Box::Locker 10 seconds manager Mail::Box undef message_type Mail::Box 'Mail::Box::Message::Parsed' notreadhead_type Mail::Box 'Mail::Box::Message::NotReadHead' notread_type Mail::Box 'Mail::Box::Message::NotParsed' realhead_type Mail::Box 'MIME::Head' remove_when_empty Mail::Box 1 save_on_exit Mail::Box 1 take_headers Mail::Box thread_body Mail::Box::Threads 0 thread_timespan Mail::Box::Threads '3 days' thread_window Mail::Box::Threads 10 Mail::Box::Tie The options added by Mail::Box * folder => FOLDERNAME Which folder to open (for read or write). When used for reading (the access option set to `"r"') the mailbox should already exist. When opened for `"rw"', we do not care, although write-permission is checked on opening. * access => MODE Access-rights to the folder. MODE can be read-only (`"r"'), append (`"a"'), and read-write (`"rw"'). These modes have nothing in common with the modes actually used to open the folder-files within this module. Folders are opened for read-only (`"r"') by default. * folderdir => DIRECTORY Where are folders written by default? You can specify a folder-name preceeded by = to explicitly state that the folder is located below this directory. * message_type => CLASS What kind of message-objects are stored in this type of folder. The default is Mail::Box::Message (which is a sub-class of MIME::Entity). The class you offer must be an extention of Mail::Box::Message. * save_on_exit => BOOL Sets the default on what to do when the folder is closed (see the close() method. When the program is terminated, or any other reason when the folder is automatically close, this flag determines what to do. By default, this is TRUE; * remove_when_empty => BOOL Remove the folder-file or directory (dependent on the type of folder) automatically when the write would result in a folder without sub-folders and messages. This is true by default. * manager => MANAGER The object which manages this folder. Typically a (sub-class of) Mail::Box::Manager. Some folder-types have the following options. You can find this in their specific manual-pages. Folders which do not support these fields will not complain. * notread_type => CLASS * notreadhead_type => CLASS * realhead_type => CLASS Three classes of objects which are usually hidden for users of this module, but especially useful if you plan to extent modules. These classes all contain parts of an incompletely read message. * lazy_extract => INTEGER * lazy_extract => CODE * lazy_extract => METHOD * lazy_extract => 'NEVER'|'ALWAYS' If you supply a number to this option, bodies of those messages with a total size less than that number will be extracted from the folder only when nessesary. Headers will always be extracted, even from the larger messages. This reduces the memory-footprint of the program, with only little cost. When you supply a code-reference, that subroutine is called every time that the extraction mechanism wants to determine whether to parse the body or not. The subroutine is called: $code->(FOLDER, HEADER, BODY, BYTES) where FOLDER is a reference to the folder we are reading. HEADER refers an array of header-lines, or a MIME::Header, but may also be undef. You have to handle all three situations. BODY refers to the array lines which form the body of the message (including message-parts), but may also be undef, dependent on the folder-type. BYTES is the size of the message in bytes including the header-lines, and always defined. This may be the best way to make a selection. The routine must return true (be lazy: delay extract) or false (extract now). The third possibility is to specify the NAME of a method. In that case, for each message is called: FOLDER->NAME(HEADER, BODY, BYTES) Where each field has the same meaning as described above. The fourth way to use this parameter involves constants: with `'NEVER'' you can disable delayed loading. With `'ALWAYS'' you force unconditional delayed-loading. Examples: $folder->new(lazy_extract => 'NEVER'); $folder->new(lazy_extract => 10000); $folder->new(lazy_extract => sub {$_[3] >= 10000 }); #same $folder->new(lazy_extract => 'sent_by_me'); sub Mail::Box::send_by_me($$$) { my ($self, $header, $lines, $bytes) = @_; $header->get('from') =~ m/\bmy\@example.com\b/i; } The Mail::Box::Message manual-page has more on this subject. * take_headers => ARRAY-REGEXPS|REGEXP|'ALL'|'REAL'|'DELAY' When messages are not parsed (as controlled by the `lazy_extract' parameter), and hence stay in their respective folders, some header-lines are still to be taken: for instance you still want access to the subject-field to be able to print an index. See `registerHeaders()' below, for a detailed explanation. Please try to avoid calling that method when you can do with using this option. Examples: $folder->new( take_headers => 'ALL'); $folder->new( take_headers => 'Subject'); $folder->new( take_headers => [ 'X-Mutt-.*', 'X-Folder-.*' ]); $folder->new( take_headers => 'REAL' , realhead_type => 'MIME::Head' ); clone [OPTIONS] Create a new folder, with the same settings as this folder. One of the specified options must be new folder to be opened. Other options overrule those of the folder where this is a clone from. Example: my $folder2 = $folder->clone(folder => '=jan'); registerHeaders REGEXP [,REGEXP, ...] registeredHeaders See the `take_header' option of new(), which is the prefered way to specify which way the header should be treated. Try to avoiding registerHeaders directly. The registerHeaders method can be used to specify more header-lines to be taken when scanning through a folder. Its counterpart registeredHeaders returns the current setting. If you know your application needs some header-fields frequently, you add them to the default list of fields which are already taken by the folder-implementation. No problem if you specify the same name twice. If you specify too few field-names, then all messages will get parsed (read from file into memory) to get the field-data you missed. When you specify too many fields, your program will consume considerable more memory. You can specify a regular expression, although you cannot use parentheses in them which do count. The expressions will be matched always on the whole field. So `X-.*' will only match lines starting with `X-'. You can not used `X-(ab|cd).*', but may say `X-(?:ab|cd).*'. There are three special constants. With ALL you get all header-lines from the message (same as pattern `.*') and REAL will cause headers to be read into a real MIME::Header structure (to be more precise: the type you specify with `realhead_type'.) Some folder-types (like MH) support DELAY, where headers are to taken at all, until a line from the header is required. This is useful for folders where each message has to be read from a seperate source. In this case, we would like to delay even that contact as long as possible. * 'ALL' to indicate that all headers should be taken. * 'REAL' indicates that all headers should be taken and translated into a real MIME::Header. * 'DELAY' requests for no header at all, unless we accidentally stumble on them. This is default (and only usefull) for all folder-types which store their messages in seperate files. Mail::Box will try to avoid opening those files with maximum effort. In case you need header-lines, and at the same time want to avoid access to each file when a folder is opened (for instance, if you want to read e-mail in threads), consider using index-files. Read the manual-page of the folder-type you need on whether those is supported for that specific type. * a list of regular expressions which specify the header-lines to be taken. Examples: $folder->registerHeaders('ALL'); $folder->registerHeaders('Subject', 'X-Folder-.*'); unfoldHeaders REF-ARRAY E-mail headers may span a few lines (folded fields). The first line has the name of the field, and is followed by one or more lines which start with some blanks. This method receives an array, and modifies it such that folder lines are rejoined with their field-name. Don't forget to fold back again when printing to file. read OPTIONS Read messages from the folder into the folder-structure. If there are already messages in this structure, the new ones are added. When to want to add messages from a different foldertype to this folder, you need to join folders, as shown in the following example. Example read folder into folder: my $folder = Mail::Box::File->new(folder => 'InBox'); my $old = Mail::Box::MH->new(folder => 'Received'); $folder->addMessages(@$old); $folder->write; $old->delete; write [OPTIONS] Write the data to disk. It returns the folder when this succeeded. If you want to write to a different file, you first create a new folder, then move the messages, and then write that file. As options you may specify * force => BOOL Overrule write-protection (if possible, it may still be blocked by the operating-system). * keep_deleted => BOOL Do not remove messages which were flaged to be deleted from the folder, but do remove them from disk. * save_deleted => BOOL Save messages which where flagged to be deleted. The flag is conserved (when possible) close OPTIONS Close the folder. It depends on the OPTIONS whether the folder is to be written or not. Futhermore, you may specify options which are passed to write, as descibed above. Options specific to close are: * write => 'ALWAYS'|'NEVER'|'MODIFIED' When must the folder be written. As could be expected, `'ALWAYS'' means always (even if there are no changes), `'NEVER'' means that changes to the folder will be lost, and `'MODIFIED'' (which is the default) only saves the folder if there are any changes. * force => BOOL Overrule the setting of access when the folder was opened. This only contributes to your program when you give it a TRUE value. However: writing to the folder not be permitted by the file-system, in which case even force will not help. delete Remove the specified folder-file or folder-directory (dependent on the type of folder) from disk. Of course, THIS IS DANGEROUS: you "may" lose data. When you first copied this folder's information into an other folder, then be sure that that folder is written to disk first! Otherwise you may loose data in case of a system-crash or software problems. Examples of instance call: my $folder = Mail::Box::File->new(folder => 'InBox'); $folder->delete; name Returns the name of this folder. What the name represents depends on the actual type of mailboxes used. Example: print $folder->name; writeable readable Checks whether the current folder is writeable respectively readable. Example: $folder->addMessage($msg) if $folder->writeable; modified modifications INCR modified checks if the folder is modified, where modifications is used to tell the folder how many changes are made in messages. The INCR value can be negative to undo effects. lazyExtract HEADER, BODY, BYTES Calls the subroutine which will perform the chech whether a message's body should be extracted or stay in the folder until used. This method calls the routine defined by the `lazy_extract' option at creation of the folder. message INDEX Get or set a message with on a certain index. Examples: my $msg = $folder->message(3); $folder->message(3)->delete; # status changes to `deleted' $folder->message(3) = $msg; messageID MESSAGE-ID [,MESSAGE] Returns the message in this folder with the specified MESSAGE-ID. This method returns a not-parsed, parsed, or dummy message. With the second MESSAGE argument, the value is first set. messages Returns all messages which are not scheduled to be deleted. In scalar context, it provides you with the number of undeleted messages in this folder. Dereferencing a folder to an array is overloaded to call this method. Examples: foreach ($folder->messages) {...} foreach (@$folder) my $remaining_size = $folder->messages; activeMessage INDEX [,MESSAGE] Returns the message indicated by INDEX from the list of non-deleted messages. This is useful for the tied-folder interface, where we only see the non-deleted messages, but not for other purposes. allMessages Returns a list of all messages in the folder, including those which are to be deleted. Examples: foreach my $msg ($folder->allMessages) { $msg->print; } my $total_size = $folder->allMessages; allMessageIDs Returns a list of all message-ids in the folder, including those which are to be deleted. For some folder-types (like MH), this method may cause all message-files to be read. See their respective manual-pages. Examples: foreach my $id ($folder->allMessageIDs) { $folder->messageID($id)->print; } addMessage MESSAGE addMessages MESSAGE [, MESSAGE, ...] Add a message to the folder. A message is usually a Mail::Box::Message object or a sub-class of that. Messages with id's which allready exist in this folder are neglected. Examples: $folder->addMessage($msg); $folder->addMessages($msg1, $msg2, ...); appendMessages OPTIONS (Class method) Append one or more messages to an unopened folder. Usually, this method is called by the Mail::Box::Manager (its method `appendMessage()'), in which case the correctness of the foldertype is checked. This method gets a list of labeled parameters, which may contain any flag which can be used when a folder is opened (most importantly folderdir). Next to these, two parameters shall be specified: * folder => FOLDERNAME The name of the folder where the messages are to be appended. When possible, the folder-implementation will avoid to open the folder for real, because that is resource consuming. * message => MESSAGE * messages => ARRAY-OF-MESSAGES One reference to a MESSAGE or a reference to an ARRAY of MESSAGEs, which may be of any type. The messages will first be coerced into the correct message-type to fit in the folder, and then be added to it. coerce MESSAGE Coerce the message to be of the correct type to be placed in the folder. messageDeleted MESSAGE|MESSAGE-ID, BOOL Signals to the folder that a message has been deleted. This method is called automatically when you call the delete method on a MESSAGE. If the BOOL is true, the message got deleted, otherwise it got undeleted. folderdir [DIR] Get or set the directory which is used to store mail-folders by default. Examples: print $folder->folderdir; $folder->folderdir("$ENV{HOME}/nsmail"); current [NR|MESSAGE|MESSAGE-ID] Returns the current message (when specified, after setting it to a new values. You may specify a NUMBER, to specify that that message-number is to be selected as current, or a MESSAGE/MESSAGE-ID (as long as you are sure that the header is already loaded, otherwise they are not recognized). Examples: $folder->current(0); $folder->current($message); DESTROY This method is called by Perl when an folder-object is not accessible anymore by the rest of the program. However... This is not accomplished automatically because (unparsed) messages reference back to their folder: there is a two-way reference which is not resolved by the perl-memory cleanup. The two ways to clean-up the folder information is * by explicitly call for a close on a folder, in which case the data may be preserved (when the `save_on_exit' flag was selected), or * by terminating the program which will cause changes to be lost. In this condition, the two-way reference will cause Perl to call the DESTROY of the folder and its messages in undefined order. It is not possible to write messages which are already removed... folder management methods ------------------------- The following class methods are used to test and list folders. The do share the folderdir option, where you can specify which is the default location for the folder-files. foundIn FOLDERNAME [,OPTIONS] (class method) Autodetect if there is a folder of a certain type specified here. This method is extended for each type of folder. The FOLDERNAME specifies the name of the folder, as is specified by the application. OPTIONS is a list of extra information on the request. Read the manual-page for each type of folder for more options, but at least each type will support * folderdir => DIRECTORY The location where the folders of this class are stored by default. If the user specifies a name starting with a =, that symbolizes that the name is to be found is this default DIRECTORY. create FOLDERNAME [, OPTIONS] (Class method) Create a folder. If the folder already exists, it will be left untouched. As options, you may specify: * folderdir => DIRECTORY When the foldername is preceeded by a =, the folderdir directory will be searched for the named folder. listFolders [OPTIONS] (Class and Instance method) List all folders which belong to a certain class of folders. Each class shall extent this method. As class method, the folder option is usually used (defaults to the top folderdir). This method will return the sub-folders of the opened folder when called as instance method. At least the following options are supported, but refer to the manpage of the various folder-classes to see more options. * folder => FOLDERNAME The folder of which the sub-folders should be listed. * folderdir => DIRECTORY * check => BOOL Specifies whether to do a very thorrow job on selecting folders. Performing a check on each file or directory (depends on the type of folder) to see if it really contains a folder can be time-consuming, so the default is off. * skip_empty => BOOL Shall empty folders (folders which currently do not contain any messages) be included? Empty folders are not useful to open, but may be useful to save to. Examples: my $folder = $mgr->open('=in/new'); my @subs = $folder->listFolders; my @subs = Mail::Box::Mbox->listFolders(folder => '=in/new'); my @subs = Mail::Box::Mbox->listFolders; # toplevel folders. AUTHOR ====== Mark Overmeer (`Mark@Overmeer.net'). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. VERSION ======= This code is beta, version 1.100