From fd81fbac82f4a55854eb08d99c0063bef1b7db8b Mon Sep 17 00:00:00 2001
From: "Edward Z. Yang" <edwardzyang@thewritingpot.com>
Date: Sun, 27 Jan 2008 05:53:13 +0000
Subject: [PATCH] Add complete handle support.

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@1519 48356398-32a2-884e-a903-53898d9a118a
---
 extras/FSTools/File.php    | 43 ++++++++++++++++++++++++++++++++++++--
 tests/FSTools/FileTest.php | 10 +++++++++
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/extras/FSTools/File.php b/extras/FSTools/File.php
index d17dce6a..a9103098 100644
--- a/extras/FSTools/File.php
+++ b/extras/FSTools/File.php
@@ -2,6 +2,10 @@
 
 /**
  * Represents a file in the filesystem
+ *
+ * @warning Be sure to distinguish between get() and write() versus
+ *      read() and put(), the former operates on the entire file, while
+ *      the latter operates on a handle.
  */
 class FSTools_File
 {
@@ -77,9 +81,44 @@ class FSTools_File
     /** Closes file's handle */
     public function close() {
         if (!$this->handle) return false;
-        $this->fs->fclose($this->handle);
+        $status = $this->fs->fclose($this->handle);
         $this->handle = false;
-        return true;
+        return $status;
+    }
+    
+    /** Retrieves a line from an open file, with optional max length $length */
+    public function getLine($length = null) {
+        if (!$this->handle) $this->open('r');
+        if ($length === null) return $this->fs->fgets($this->handle);
+        else return $this->fs->fgets($this->handle, $length);
+    }
+    
+    /** Retrieves a character from an open file */
+    public function getChar() {
+        if (!$this->handle) $this->open('r');
+        return $this->fs->fgetc($this->handle);
+    }
+    
+    /** Retrieves an $length bytes of data from an open data */
+    public function read($length) {
+        if (!$this->handle) $this->open('r');
+        return $this->fs->fread($this->handle, $length);
+    }
+    
+    /** Writes to an open file */
+    public function put($string) {
+        if (!$this->handle) $this->open('a');
+        return $this->fs->fwrite($this->handle, $string);
+    }
+    
+    /** Returns TRUE if the end of the file has been reached */
+    public function eof() {
+        if (!$this->handle) return true;
+        return $this->fs->feof($this->handle);
+    }
+    
+    public function __destruct() {
+        if ($this->handle) $this->close();
     }
     
 }
diff --git a/tests/FSTools/FileTest.php b/tests/FSTools/FileTest.php
index 360c12da..7a3ca680 100644
--- a/tests/FSTools/FileTest.php
+++ b/tests/FSTools/FileTest.php
@@ -2,6 +2,9 @@
 
 require_once 'FSTools/FileSystemHarness.php';
 
+/**
+ * These are not really unit tests, just sanity checks of basic functionality.
+ */
 class FSTools_FileTest extends FSTools_FileSystemHarness
 {
     
@@ -28,7 +31,14 @@ class FSTools_FileTest extends FSTools_FileSystemHarness
         $this->assertFalse($file->exists());
         $file->open('w');
         $this->assertTrue($file->exists());
+        $file->put('Foobar');
         $file->close();
+        $file->open('r');
+        $this->assertIdentical('F', $file->getChar());
+        $this->assertFalse($file->eof());
+        $this->assertIdentical('oo', $file->read(2));
+        $this->assertIdentical('bar', $file->getLine());
+        $this->assertTrue($file->eof());
     }
     
 }