File Coverage

blib/lib/Mac/RecentDocuments.pm
Criterion Covered Total %
statement 9 22 40.9
branch 1 8 12.5
condition 0 6 0.0
subroutine 4 6 66.6
pod 3 3 100.0
total 17 45 37.7


line stmt bran cond sub pod time code
1              
2             require 5;
3             package Mac::RecentDocuments;
4 2     2   11249 use strict; # Time-stamp: "2004-12-29 18:58:03 AST"
  2         7  
  2         112  
5 2     2   23 use vars qw($RD $SF $OK $AM @ISA @EXPORT %EXPORT_TAGS $VERSION);
  2         4  
  2         1302  
6             $VERSION = '1.02';
7              
8             require Exporter;
9             @ISA = ('Exporter');
10             @EXPORT = ('recent_document', 'recent_documents');
11             %EXPORT_TAGS = (
12             'all' => \@EXPORT,
13             'none' => [],
14             );
15              
16             =head1 NAME
17              
18             Mac::RecentDocuments -- add items to the MacOS Recent Documents menu
19              
20             =head1 SYNOPSIS
21              
22             use Mac::RecentDocuments qw(:ARGV);
23             # Adds all files in @ARGV to Recent Documents folder,
24             # and imports recent_documents and recent_document
25            
26             foreach my $in (@ARGV) {
27             open(IN, "<$in") or die "Can't read-open $in: $!";
28             my $out = $in . '2';
29             die "But $out already exists!" if -e $out;
30             open(OUT, ">$out") or die "Can't write-open $out: $!";
31            
32             ...do whatever to $out...
33            
34             recent_documents($out); # add to Recent Documents folder
35             }
36              
37             =head1 DESCRIPTION
38              
39             This module provides a function that adds specified files to the
40             MacOS Apple Menu "Recent Documents" folder. You can use this module
41             under non-MacOS environments, and it will compile, but it will do
42             nothing.
43              
44             =head1 FUNCTIONS
45              
46             =over
47              
48             =item recent_documents( ...files... )
49              
50             This adds the given items to the Recent Documents folder, for each item
51             that is a pathspec to an existing file. Relative (C<":bar.txt">) as
52             well as absolute filespecs (C<"Lame Drive:stuff:bar.txt">) should work
53             equally well.
54              
55             The number of aliases that this creates in the Recent Documents folder
56             is returned.
57              
58             Under non-MacOS environments, this function does nothing at all, and
59             always returns 0.
60              
61             =item recent_document( file )
62              
63             This is just an alias to C
64              
65             =item Mac::RecentDocuments::OK()
66              
67             This function returns true iff you are running under MacOS, and if, at
68             compile-time, Mac::RecentDocuments was able to find your Recent
69             Documents folder, and verified that it was a writeable directory.
70             In all other cases, this returns false.
71              
72             =back
73              
74             =head1 IMPORTING, AND :ARGV
75              
76             If you say
77              
78             use Mac::RecentDocuments;
79              
80             then this will by default import the functions C
81             and C.
82              
83             This is equivalent to:
84              
85             use Mac::RecentDocuments qw(:all);
86              
87             If you want to use the module but import no functions, you can say:
88              
89             use Mac::RecentDocuments ();
90              
91             or
92              
93             use Mac::RecentDocuments qw(:none);
94              
95             This module also defines a use-option C<":ARGV"> that causes
96             Mac::RecentDocuments to also call C, at compile
97             time. This should be rather useful with MacPerl droplets.
98              
99             That is, this:
100              
101             use Mac::RecentDocuments qw(:ARGV);
102              
103             is basically equivalent to:
104              
105             BEGIN {
106             use Mac::RecentDocuments;
107             Mac::RecentDocuments(@ARGV);
108             }
109              
110             (The only difference is that if several instances of
111             C are seen in a given session,
112             C is called only the first time.)
113              
114             When "qw(:ARGV)" is the whole option list, it is interpreted as
115             equivalent to "qw(:ARGV :all)". If you want the C<:ARGV> option
116             without importing anything, explicitly specify the C<":none">
117             option:
118              
119             use Mac::RecentDocuments qw(:ARGV :none);
120              
121             =head1 CAVEATS
122              
123             The module is called Mac::RecentDocuments (no underscore), but
124             the function is called C (with underscore).
125              
126             The module is called Mac::RecentDocuments, not Mac::RecentFiles.
127              
128             =head1 THANKS
129              
130             Thanks to Chris Nandor for the C tips.
131              
132             =head1 COPYRIGHT
133              
134             Copyright (c) 2000 Sean M. Burke. All rights reserved.
135              
136             This library is free software; you can redistribute it and/or modify
137             it under the same terms as Perl itself.
138              
139             =head1 AUTHOR
140              
141             Sean M. Burke C
142              
143             =cut
144              
145             #--------------------------------------------------------------------------
146              
147             $OK = 0;
148              
149 1     1 1 42 sub OK () {$OK}
150              
151 0     0 1 0 sub recent_document { goto &recent_documents } # alias
152              
153             #--------------------------------------------------------------------------
154             my $already_argved = 0;
155             sub import {
156 1 50   1   10 if(@_ > 1) {
157 0         0 my $argvy;
158 0         0 for(my $i = 1; $i < @_;) {
159 0 0       0 if($_[$i] eq ':ARGV') {
160 0         0 $argvy = 1;
161 0         0 splice(@_,$i,1); # remove the ':ARGV'
162             } else {
163 0         0 ++$i;
164             }
165             }
166 0 0 0     0 if($OK and $argvy and not $already_argved) {
      0        
167 0         0 recent_documents(@ARGV);
168 0         0 $already_argved = 1;
169             }
170 0 0       0 if(@_ == 1) { # did we just empty the list?
171 0         0 push @_, @EXPORT;
172             }
173             }
174 1         3514 goto &Exporter::import;
175             }
176              
177             #--------------------------------------------------------------------------
178             if(!$MacPerl::Version) {
179             $OK = 0;
180 0     0 1   eval 'sub recent_documents { 0 }';
181             die $@, ' in ', __PACKAGE__ if $@; # should never fail!
182             } else {
183             eval <<'EOMAC'; # cook up the MacPerl-specific code:
184              
185             # Init code :
186             unless(defined $RD) {
187             require Mac::Files;
188             $RD = Mac::Files::FindFolder(
189             Mac::Files::kOnSystemDisk(),
190             'rdoc' # kRecentDocumentsFolderType
191             ); # will work on only recent MacOS versions
192              
193             unless(defined $RD) {
194             $AM = Mac::Files::FindFolder(
195             Mac::Files::kOnSystemDisk(),
196             Mac::Files::kAppleMenuFolderType()
197             ); # should work anywhere
198             if($AM and -e $AM) {
199             $RD = $AM . ':Recent Documents';
200             } else {
201             #print "No AM: $AM?\n";
202             }
203             }
204              
205             unless(defined $RD) {
206             $SF = Mac::Files::FindFolder(
207             Mac::Files::kOnSystemDisk(),
208             Mac::Files::kSystemFolderType()
209             ); # should REALLY work anywhere
210             if($SF and -e $SF) {
211             $RD = $SF . ':Apple Menu Items:Recent Documents';
212             } else {
213             #print "No SF: $SF?\n";
214             }
215             }
216              
217             unless(defined $RD and -e $RD and -d _ and -w _) {
218             #print "No RD ($RD)?\n";
219             $RD = undef;
220             $OK = 0; # ahwell, give up
221             } else {
222             $OK = 1;
223             }
224             }
225              
226             sub recent_documents {
227             return 0 unless @_ and $OK;
228             my $successes = 0;
229             my $new;
230             foreach my $item (@_) {
231             next unless defined $item
232             and $item =~ m/([^:]+)$/;
233             $new = $RD . ':' . $1;
234            
235             next unless -e $item and -f _; # let only existing files thru
236             #print "Trying $item -> $new\n";
237             unlink($new); # which does nothing if there is none there
238             # That presumably was a mere alias, tho.
239             # Anyone putting real items in their RD folder gets what
240             # they deserve.
241             if(symlink($item, $new)) {
242             #print "OK\n";
243             ++$successes;
244             } else {
245             #print "<$!>\n";
246             }
247             }
248             return $successes;
249             }
250             EOMAC
251             ;
252             die $@, ' in ', __PACKAGE__ if $@; # shouldn't fail!
253             }
254              
255             #--------------------------------------------------------------------------
256             1;