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