CodeDweller/filesystem.hpp

// \file filesystem.hpp
//
// Copyright (C) 2015 MicroNeil Research Corporation.
//
// This program is part of the MicroNeil Research Open Library Project. For
// more information go to http://www.microneil.com/OpenLibrary/index.html
//
// This program is free software; you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the
// Free Software Foundation; either version 2 of the License, or (at your
// option) any later version.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
// more details.
//
// You should have received a copy of the GNU General Public License along with
// this program; if not, write to the Free Software Foundation, Inc., 59 Temple
// Place, Suite 330, Boston, MA 02111-1307 USA
//==============================================================================

/*
  \brief The filesystem module provides classes to access the filesystem.
*/

#ifndef FILESYSTEM_HPP
#define FILESYSTEM_HPP

#include <ctime>

#include <string>
#include <vector>
#include <initializer_list>

namespace CodeDweller {

  /** Abstracts OS specifics for manipulating file paths. */
  class FilePath {

  public:

    /// Directory separator character.
    static char const DirectorySeparator;

    /** Join path components.

	This method joins a veriable number of std::string inputs to
	form a path.

	@param[in] component... is one or more components of a
	path (i.e. directory names or a file name).

	@returns the path consisting of all the pathComponent inputs.

    */
    static std::string join(std::initializer_list<std::string> components);

  };

  /** Abstracts OS specifics for identifying a file and provides
      access to meta data.
  */
  class FileReference {

  public:

    /** Initialize with the name of the file.

	The constructor updates the FileReference object with the file
	status except for the full path.

        @param[in] fileName is the name of the file.

    */
    FileReference(std::string fileName);

    /** Get the name passed to the constructor.

	@returns the name passed to the constructor.

    */
    std::string FileName() const;

    /** Return timestamp.

	@returns the epoch modification time of the file if the file
        existed when the FileReference object was created, or the last
        time refersh() was called (whichever is more recent), 0
        otherwise.

    */
    time_t ModTimestamp() const;

    /** Get the file size.

	@returns the size of the file if the file existed when the
        FileReference object was created, or the last time refersh()
        was called (whichever is more recent), 0 otherwise.

    */
    size_t Size() const;

    /** Get full path if the file exists.

	This method access the filesystem to get the full path of the
	file.

	@warning This method might fail under Windows in a
	multi-threaded application if the current working directory of
	the application is being changed by a thread while this method
	is invoked.

        @returns a fully referenced path to the file if the file
        exists.  Otherwise, "" is returned.
    */
    std::string FullPath();

    /** Refreshes the FileReference object.

	This method updates the FileReference object with the current
        data on the file system, except for the full path.

    */
    void refresh();

    /** Check if the file exists.

        @returns true if the file reference name existed in the file
        system when the FileReference object was created, or the last
        time refersh() was called (whichever is more recent), false
        otherwise.

        @throws std::runtime_error if an error occurs.

    */
    bool exists() const;

    /** Check if the file is a directory.

        @returns true if the file reference name existed and was a
        directory in the file system when the FileReference object was
        created, or the last time refersh() was called (whichever is
        more recent), false otherwise.

    */
    bool isDirectory() const;

    /// Return text for the most recent error.
    //
    // \returns Human-readable description of the most recent error.
    //
    static std::string getErrorText();

  private:

    /// Reset all members but the name. */
    void reset();

    /** Name provided to constructor. */
    std::string name;

    /** Full path. */
    std::string path;

    /** Timestamp. */
    time_t modTimestamp;

    /** Size in bytes. */
    long size_bytes;

    /** True if the file exists, false otherwise. */
    bool fileExists;

    /** True if the file is a directory, false otherwise. */
    bool fileIsDirectory;

  };

  /** Abstracts OS specifics for scanning a directory and provides
      access to meta data.
  */

  class DirectoryReference : public std::vector<FileReference> {

  public:

    /** Initialize by scanning the directory.

	The constructor updates the DirectoryReference object with the
        listing of the specified directory, filtered by the specified
        function.

        @param[in] dirName is the name of the directory.

        @param[in] filter is the function used to filter the directory
        listing.  It inputs the name of the file, and returns true if
        the file is is to be included in the listing, and false
        otherwise.

    */
    DirectoryReference(std::string dirName, bool (*dirFilter)(std::string) = 0);

    /** Refreshes the DirectoryReference object.

	This method updates the DirectoryReference object with the
        current listing on the file system.

    */
    void refresh();

  private:

    /** Directory name provided to constructor. */
    std::string name;

    /** Filter function. */
    bool (*filter)(std::string);

  };

}

#endif // FILESYSTEM_HPP