More patterns added, part description changed to object description
[shipsimu.git] / inc / classes / main / io / class_FrameworkDirectoryPointer.php
1 <?php
2 /**
3  * A class for directory reading and getting its contents
4  *
5  * @author              Roland Haeder <webmaster@mxchange.org>
6  * @version             0.3.0
7  * @copyright   Copyright(c) 2007, 2008 Roland Haeder, this is free software
8  * @license             GNU GPL 3.0 or any newer version
9  * @link                http://www.mxchange.org
10  *
11  * This program is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation, either version 3 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
23  */
24 class FrameworkDirectoryPointer extends BaseFrameworkSystem {
25         /**
26          * The current path we are working in
27          */
28         private $pathName = "";
29
30         /**
31          * The directory pointer
32          */
33         private $dirPointer = null;
34
35         /**
36          * Private constructor
37          */
38         private function __construct () {
39                 // Call parent constructor
40                 parent::constructor(__CLASS__);
41
42                 // Set part description
43                 $this->setObjectDescription("Verzeichnis-Handler");
44
45                 // Create unique ID
46                 $this->createUniqueID();
47
48                 // Clean-up a little
49                 $this->removeNumberFormaters();
50         }
51
52         /**
53          * Destructor for cleaning purposes, etc
54          */
55         public function __destruct() {
56                 // Is there a resource pointer? Then we have to close the directory here!
57                 if (is_resource($this->getPointer())) {
58                         // Try to close a directory
59                         $this->closeDirectory();
60                 }
61
62                 // Call the parent destructor
63                 parent::__destruct();
64         }
65
66         /**
67          * Create a directory pointer based on the given path. The path will also
68          * be verified here.
69          *
70          * @param               $pathName                                       The path name we shall pass
71          *                                                                      to opendir()
72          * @param               $inConstructor                          If we are in de/con-structor
73          *                                                                      or from somewhere else
74          * @throws      PathIsEmptyException            If the provided path name
75          *                                                                      is empty
76          * @throws      InvalidPathStringException      If the provided path name is
77          *                                                                      not a string
78          * @throws      PathIsNoDirectoryException      If the provided path name is
79          *                                                                      not valid
80          * @throws      PathReadProtectedException      If the provided path name is
81          *                                                                      read-protected
82          * @throws      DirPointerNotOpened                     If opendir() returns not a
83          *                                                                      directory resource
84          * @return      $pointerInstance                        A prepared instance of
85          *                                                                      FrameworkDirectoryPointer
86          */
87         public final static function createFrameworkDirectoryPointer ($pathName, $inConstructor = false) {
88                 // Some pre-sanity checks...
89                 if (is_null($pathName)) {
90                         // No pathname given
91                         if ($inConstructor) {
92                                 return null;
93                         } else {
94                                 throw new PathIsEmptyException(null, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
95                         }
96                 } elseif (!is_string($pathName)) {
97                         // Is not a string
98                         if ($inConstructor) {
99                                 return null;
100                         } else {
101                                 throw new InvalidPathStringException(null, self::EXCEPTION_INVALID_STRING);
102                         }
103                 } elseif (!is_dir($pathName)) {
104                         // Not a directory
105                         if ($inConstructor) {
106                                 return null;
107                         } else {
108                                 throw new PathIsNoDirectoryException($pathName, self::EXCEPTION_INVALID_PATH_NAME);
109                         }
110                 } elseif (!is_readable($pathName)) {
111                         // Not readable
112                         if ($inConstructor) {
113                                 return null;
114                         } else {
115                                 throw new PathReadProtectedException($pathName, self::EXCEPTION_READ_PROTECED_PATH);
116                         }
117                 }
118
119                 // Try to open a handler
120                 $dirPointer = @opendir($pathName);
121                 if (!is_resource($dirPointer)) {
122                         // Something bad happend
123                         if ($inConstructor) {
124                                 return null;
125                         } else {
126                                 throw new DirPointerNotOpenedException($pathName, self::EXCEPTION_DIR_POINTER_INVALID);
127                         }
128                 }
129
130                 // Create new instance
131                 $pointerInstance = new FrameworkDirectoryPointer();
132
133                 // Set directory pointer and path name
134                 $pointerInstance->setPointer($dirPointer);
135                 $pointerInstance->setPathName($pathName);
136
137                 // Return the instance
138                 return $pointerInstance;
139         }
140
141         /**
142          * Read raw lines of data from a directory pointer and return the data
143          *
144          * @return      string  Directory and/or file names read from the current
145          *                                      directory pointer
146          * @throws      NullPointerException    If the directory pointer instance
147          *                                                              is not set by setPointer()
148          * @throws      InvalidDirectoryResourceException       If there is being set
149          *                                                                              an invalid directory resource
150          */
151         public function readRawDirectory () {
152                 if (is_null($this->getPointer())) {
153                         // Pointer not initialized
154                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
155                 } elseif (!is_resource($this->getPointer())) {
156                         // Pointer is not a valid resource!
157                         throw new InvalidDirectoryResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
158                 }
159
160                 // Read data from the directory pointer and return it
161                 return readdir($this->getPointer());
162         }
163
164         /**
165          * Read lines from the current directory pointer except some parts
166          *
167          * @param               $except Some parts of a directory we want to ignore.
168          *                                      Valid: dirs
169          *                                      Other values will be silently ignored
170          * @return      string  Directory and/or file names read from the current
171          *                                      directory pointer
172          */
173         public function readDirectoryExcept ($except = "") {
174                 if ((empty($except)) || (!is_array($except)) || (count($except) == 0)) {
175                         // No exception given, so read all data
176                         return $this->readRawDirectory();
177                 }
178
179                 // Read a raw line...
180                 $rawLine = $this->readRawDirectory();
181
182                 // Shall we exclude directories?
183                 if ((!is_null($rawLine)) && ($rawLine !== false) && (in_array($rawLine, $except))) {
184                         // Exclude this part
185                         return $this->readDirectoryExcept($except);
186                 } elseif ((!is_null($rawLine)) && ($rawLine !== false)) {
187                         // Return read data
188                         return $rawLine;
189                 }
190
191                 // End pointer reached
192                 return null;
193         }
194
195         /**
196          * Close a directory source and set it's instance to null and the path name
197          * to empty
198          *
199          * @return      void
200          * @throws      NullPointerException    If the directory pointer instance
201          *                                                              is not set by setPointer()
202          * @throws      InvalidDirectoryResourceException       If there is being set
203          */
204         public function closeDirectory () {
205                 if (is_null($this->getPointer())) {
206                         // Pointer not initialized
207                         return;
208                 } elseif (!is_resource($this->getPointer())) {
209                         // Pointer is not a valid resource!
210                         throw new InvalidDirectoryResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
211                 }
212
213                 // Close the directory pointer and reset the instance variable
214                 @closedir($this->getPointer());
215                 $this->setPointer(null);
216                 $this->setPathName("");
217         }
218
219         /**
220          * Setter for the directory pointer
221          *
222          * @param               $dirPointer     The directory resource
223          * @return      void
224          */
225         public final function setPointer ($dirPointer) {
226                 // Sanity-check if the pointer is a valid directory resource
227                 if (is_resource($dirPointer) || is_null($dirPointer)) {
228                         // Is a valid resource
229                         $this->dirPointer = $dirPointer;
230                 } else {
231                         // Throw exception
232                         throw new InvalidDirectoryResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
233                 }
234         }
235
236         /**
237          * Getter for the directory pointer
238          *
239          * @return      $dirPointer     The directory pointer which shall be a valid
240          *                                              directory resource
241          */
242         public final function getPointer () {
243                 return $this->dirPointer;
244         }
245
246         /**
247          * Setter for path name
248          *
249          * @param               $pathName               The new path name
250          * @return      void
251          */
252         public final function setPathName ($pathName) {
253                 $pathName = (string) $pathName;
254                 $this->pathName = $pathName;
255         }
256
257         /**
258          * Getter for path name
259          *
260          * @return      $pathName               The current path name
261          */
262         public final function getPathName () {
263                 return $this->pathName;
264         }
265 }
266
267 // [EOF]
268 ?>