File Coverage

blib/lib/Filesys/POSIX/Directory.pm
Criterion Covered Total %
statement 25 25 100.0
branch n/a
condition n/a
subroutine 16 16 100.0
pod 13 13 100.0
total 54 54 100.0


line stmt bran cond sub pod time code
1             # Copyright (c) 2014, cPanel, Inc.
2             # All rights reserved.
3             # http://cpanel.net/
4             #
5             # This is free software; you can redistribute it and/or modify it under the same
6             # terms as Perl itself. See the LICENSE file for further details.
7              
8             package Filesys::POSIX::Directory;
9              
10 27     27   92 use strict;
  27         30  
  27         581  
11 27     27   81 use warnings;
  27         27  
  27         548  
12              
13 27     27   80 use Carp qw(confess);
  27         28  
  27         6816  
14              
15             =head1 NAME
16              
17             Filesys::POSIX::Directory - Base class for implementing directory structures
18              
19             =head1 DESCRIPTION
20              
21             Filesys::POSIX::Directory is a common interface used to implement classes that
22             act like directories, and should be able to be accessed randomly or in an
23             iterative fashion.
24              
25             Classes which wish to implement the interface documented herein should provide
26             implementations for ALL methods listed in this document, in the manner in which
27             they are described within this document.
28              
29             =head1 RANDOM ACCESS
30              
31             =over
32              
33             =item C<$directory-Eget($name)>
34              
35             If the current directory contains an item named for C<$name>, return the
36             corresponding inode. Otherwise, an C is returned.
37              
38             =cut
39              
40             sub get {
41 1     1 1 362 confess('Not implemented');
42             }
43              
44             =item C<$directory-Eset($name, $inode)>
45              
46             Store a reference to C<$inode> in the current directory, named after the member
47             label C<$name>. If an item already exists for C<$name>, then it will be
48             replaced by C<$inode>.
49              
50             =cut
51              
52             sub set {
53 1     1 1 703 confess('Not implemented');
54             }
55              
56             =item C<$directory-Eexists($name)>
57              
58             Returns true if a member called C<$name> exists in the current directory.
59             Returns false if no such member inode is listed.
60              
61             =cut
62              
63             sub exists {
64 1     1 1 596 confess('Not implemented');
65             }
66              
67             =item C<$directory-Edetach($name)>
68              
69             Drop any references to a member called C<$name> in the current directory. No
70             side effects outside of the directory object instance shall occur.
71              
72             =cut
73              
74             sub detach {
75 1     1 1 580 confess('Not implemented');
76             }
77              
78             =item C<$directory-Edelete($name)>
79              
80             Drop any references to a member called C<$name> in the current directory. Side
81             effects to other system resources referenced by this directory member may
82             potentially occur, depending on the specific directory implementation.
83              
84             =cut
85              
86             sub delete {
87 1     1 1 580 confess('Not implemented');
88             }
89              
90             =back
91              
92             =head1 LIST ACCESS
93              
94             =over
95              
96             =item C<$directory-Elist()>
97              
98             Return a list of all items in the current directory, including C<.> and C<..>.
99              
100             =cut
101              
102             sub list {
103 1     1 1 630 confess('Not implemented');
104             }
105              
106             =item C<$directory-Ecount()>
107              
108             Return the number of all items in the current directory, including C<.> and
109             C<..>.
110              
111             =cut
112              
113             sub count {
114 1     1 1 621 confess('Not implemented');
115             }
116              
117             =item C<$directory-Eempty()>
118              
119             Returns true if the directory only contains the C<.> and C<..> entries.
120              
121             =cut
122              
123             sub empty {
124 4     4 1 4 my ($self) = @_;
125              
126 4         7 return $self->count == 2;
127             }
128              
129             =back
130              
131             =head1 ITERATIVE ACCESS
132              
133             =over
134              
135             =item C<$directory-Eopen()>
136              
137             Prepare the current directory object for iterative reading access.
138              
139             =cut
140              
141             sub open {
142 1     1 1 633 confess('Not implemented');
143             }
144              
145             =item C<$directory-Erewind()>
146              
147             Rewind the current directory object to the beginning of the directory list when
148             being accessed iteratively.
149              
150             =cut
151              
152             sub rewind {
153 1     1 1 651 confess('Not implemented');
154             }
155              
156             =item C<$directory-Eread()>
157              
158             Read and return a single item from the directory, advancing the pointer to the
159             next item to be read, if any. A list containing both the name of the object,
160             and the inode it references, are returned.
161              
162             =cut
163              
164             sub read {
165 1     1 1 603 confess('Not implemented');
166             }
167              
168             =item C<$directory-Eclose()>
169              
170             Close the current directory for iterative access.
171              
172             =cut
173              
174             sub close {
175 1     1 1 588 confess('Not implemented');
176             }
177              
178             =item C<$directory-Erename_member()>
179              
180             Rename an item from one Filesys::POSIX::Directory so that it becomes
181             a member of another Filesys::POSIX::Directory and/or changes name.
182              
183             =cut
184              
185             sub rename_member {
186 4     4 1 4 my ( $self, $inode, $old_dir, $old_name, $new_name ) = @_;
187 4         10 $old_dir->detach($old_name);
188 4         10 $self->set( $new_name, $inode );
189             }
190              
191             =back
192              
193             =cut
194              
195             1;
196              
197             __END__