<?php

/**
 * 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
{

    /** Filename of file this object represents */
    protected $name;

    /** Handle for the file */
    protected $handle = false;

    /** Instance of FSTools for interfacing with filesystem */
    protected $fs;

    /**
     * Filename of file you wish to instantiate.
     * @note This file need not exist
     */
    public function __construct($name, $fs = false)
    {
        $this->name = $name;
        $this->fs = $fs ? $fs : FSTools::singleton();
    }

    /** Returns the filename of the file. */
    public function getName() {return $this->name;}

    /** Returns directory of the file without trailing slash */
    public function getDirectory() {return $this->fs->dirname($this->name);}

    /**
     * Retrieves the contents of a file
     * @todo Throw an exception if file doesn't exist
     */
    public function get()
    {
        return $this->fs->file_get_contents($this->name);
    }

    /** Writes contents to a file, creates new file if necessary */
    public function write($contents)
    {
        return $this->fs->file_put_contents($this->name, $contents);
    }

    /** Deletes the file */
    public function delete()
    {
        return $this->fs->unlink($this->name);
    }

    /** Returns true if file exists and is a file. */
    public function exists()
    {
        return $this->fs->is_file($this->name);
    }

    /** Returns last file modification time */
    public function getMTime()
    {
        return $this->fs->filemtime($this->name);
    }

    /**
     * Chmod a file
     * @note We ignore errors because of some weird owner trickery due
     *       to SVN duality
     */
    public function chmod($octal_code)
    {
        return @$this->fs->chmod($this->name, $octal_code);
    }

    /** Opens file's handle */
    public function open($mode)
    {
        if ($this->handle) $this->close();
        $this->handle = $this->fs->fopen($this->name, $mode);
        return true;
    }

    /** Closes file's handle */
    public function close()
    {
        if (!$this->handle) return false;
        $status = $this->fs->fclose($this->handle);
        $this->handle = false;
        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();
    }

}

// vim: et sw=4 sts=4