Minor code improvements:
[shipsimu.git] / inc / classes / main / io / class_FrameworkFileInputPointer.php
1 <?php
2 /**
3  * A class for reading files
4  *
5  * @author              Roland Haeder <webmaster@ship-simu.org>
6  * @version             0.0.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.ship-simu.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 FrameworkFileInputPointer extends BaseFrameworkSystem {
25         /**
26          * The current file we are working in
27          */
28         private $fileName = "";
29
30         /**
31          * The file pointer
32          */
33         private $filePointer = null;
34
35         /**
36          * Protected constructor
37          *
38          * @return      void
39          */
40         protected function __construct () {
41                 // Call parent constructor
42                 parent::__construct(__CLASS__);
43
44                 // Set part description
45                 $this->setObjectDescription("Handler for reading from files");
46
47                 // Create unique ID
48                 $this->generateUniqueId();
49
50                 // Clean-up a little
51                 $this->removeNumberFormaters();
52         }
53
54         /**
55          * Destructor for cleaning purposes, etc
56          *
57          * @return      void
58          */
59         public final function __destruct() {
60                 // Is there a resource pointer? Then we have to close the file here!
61                 if (is_resource($this->getPointer())) {
62                         // Try to close a file
63                         $this->closeFile();
64                 }
65
66                 // Call the parent destructor
67                 parent::__destruct();
68         }
69
70         /**
71          * Create a file pointer based on the given file. The file will also
72          * be verified here.
73          *
74          * @param               $fileName       The file name we shall pass to fopen()
75          * @throws      FileIsEmptyException    If the provided file name is empty.
76          * @throws      FilePointerNotOpenedException   If fopen() returns not a
77          *                                                                                      file resource
78          * @return      void
79          */
80         public final static function createFrameworkFileInputPointer ($fileName) {
81                 // Some pre-sanity checks...
82                 if ((is_null($fileName)) || (empty($fileName))) {
83                         // No filename given
84                         throw new FileIsEmptyException(null, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
85                 } elseif (!file_exists($fileName)) {
86                         // File does not exist!
87                         throw new FileNotFoundException($fileName, self::EXCEPTION_FILE_NOT_FOUND);
88                 } elseif (!is_readable($fileName)) {
89                         // File does not exist!
90                         throw new FileReadProtectedException($fileName, self::EXCEPTION_FILE_CANNOT_BE_READ);
91                 }
92
93                 // Try to open a handler
94                 $filePointer = @fopen($fileName, 'rb');
95                 if ((is_null($filePointer)) || ($filePointer === false)) {
96                         // Something bad happend
97                         throw new FilePointerNotOpenedException ($fileName, self::EXCEPTION_FILE_POINTER_INVALID);
98                 } // END - if
99
100                 // Create new instance
101                 $pointerInstance = new FrameworkFileInputPointer();
102
103                 // Set file pointer and file name
104                 $pointerInstance->setPointer($filePointer);
105                 $pointerInstance->setFileName($fileName);
106
107                 // Return the instance
108                 return $pointerInstance;
109         }
110
111         /**
112          * Read data a file pointer
113          *
114          * @return      mixed   The result of fread()
115          * @throws      NullPointerException    If the file pointer instance
116          *                                                                      is not set by setPointer()
117          * @throws      InvalidFileResourceException    If there is being set
118          *                                                                      an invalid file resource
119          */
120         public function readFromFile () {
121                 if (is_null($this->getPointer())) {
122                         // Pointer not initialized
123                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
124                 } elseif (!is_resource($this->getPointer())) {
125                         // Pointer is not a valid resource!
126                         throw new InvalidFileResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
127                 }
128
129                 // Read data from the file pointer and return it
130                 return fread($this->getPointer(), 1024);
131         }
132
133         /**
134          * Read lines from a file pointer
135          *
136          * @return      mixed   The result of fread()
137          * @throws      NullPointerException    If the file pointer instance
138          *                                                                      is not set by setPointer()
139          * @throws      InvalidFileResourceException    If there is being set
140          *                                                                      an invalid file resource
141          */
142         public function readLinesFromFile () {
143                 if (is_null($this->getPointer())) {
144                         // Pointer not initialized
145                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
146                 } elseif (!is_resource($this->getPointer())) {
147                         // Pointer is not a valid resource!
148                         throw new InvalidFileResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
149                 }
150
151                 // Read data from the file pointer and return it
152                 return fgets($this->getPointer(), 1024);
153         }
154
155         /**
156          * Close a file source and set it's instance to null and the file name
157          * to empty
158          *
159          * @return      void
160          * @throws      NullPointerException    If the file pointer instance
161          *                                                                      is not set by setPointer()
162          * @throws      InvalidFileResourceException    If there is being set
163          */
164         public function closeFile () {
165                 if (is_null($this->getPointer())) {
166                         // Pointer not initialized
167                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
168                 } elseif (!is_resource($this->getPointer())) {
169                         // Pointer is not a valid resource!
170                         throw new InvalidFileResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
171                 }
172
173                 // Close the file pointer and reset the instance variable
174                 @fclose($this->getPointer());
175                 $this->setPointer(null);
176                 $this->setFileName("");
177         }
178
179         /**
180          * Setter for the file pointer
181          *
182          * @param       $filePointer    File resource
183          * @return      void
184          */
185         public final function setPointer ($filePointer) {
186                 // Sanity-check if the pointer is a valid file resource
187                 if (is_resource($filePointer) || is_null($filePointer)) {
188                         // Is a valid resource
189                         $this->filePointer = $filePointer;
190                 } else {
191                         // Throw exception
192                         throw new InvalidFileResourceException($this, self::EXCEPTION_INVALID_DIRECTORY_POINTER);
193                 }
194         }
195
196         /**
197          * Getter for the file pointer
198          *
199          * @return      $filePointer    The file pointer which shall be a valid
200          *                                                      file resource
201          */
202         public final function getPointer () {
203                 return $this->filePointer;
204         }
205
206         /**
207          * Setter for file name
208          *
209          * @param       $fileName       The new file name
210          * @return      void
211          */
212         public final function setFileName ($fileName) {
213                 $fileName = (string) $fileName;
214                 $this->fileName = $fileName;
215         }
216
217         /**
218          * Getter for file name
219          *
220          * @return      $fileName       The current file name
221          */
222         public final function getFileName () {
223                 return $this->fileName;
224         }
225 }
226
227 // [EOF]
228 ?>