README for Mac::RecentDocuments

Time-stamp: "2000-10-12 17:07:29 MDT"

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);

CAVEAT

     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

PREREQUISITES

This suite requires Perl 5; I've only used it under Perl 5.004, so for anything lower, you're on your own.

Mac::RecentDocuments doesn't use any nonstandard modules.

MACPERL INSTALLATION NOTES

Don't bother with the makefiles. Just make a Mac directory in your MacPerl site_lib or lib directory, and move RecentDocuments.pm into there.

INSTALLATION

You install Mac::RecentDocuments, as you would install any perl module library, by running these commands:

perl Makefile.PL
make
make test
make install

If you want to install a private copy of Mac::RecentDocuments in your home directory, then you should try to produce the initial Makefile with something like this command:

perl Makefile.PL LIB=~/perl

DOCUMENTATION

POD-format documentation is included in ISA.pm. POD is readable with the 'perldoc' utility or the Shuck program under MacOS. See ChangeLog for recent changes.

SUPPORT

Questions, bug reports, useful code bits, and suggestions for Mac::RecentDocuments should just be sent to me at sburke@cpan.org

AVAILABILITY

The latest version of Mac::RecentDocuments is available from the Comprehensive Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN site near you.