file_path_class.h

Go to the documentation of this file.

/*! \file
  \brief  A class to handle file paths.

  \par Copyright Information

  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/
#ifndef INCLUDED_FILE_PATH_CLASS_H
#define INCLUDED_FILE_PATH_CLASS_H

#include "disti_metadata.h"
#include "util.h" // This is glstudio specific
#include <string>

namespace disti
{
/** \class FilePathClass
  * 
  * The FilePathClass represents a single absolute path.
  * There are methods for getting the directory, filename, 
  * file extension, and checking the validity of the path.
  * You can get a relative path string by comparing two FilePathClass objects. 
  * FilePathClass also has methods for reading/writing absolute or relative
  * path strings, the class remembers which was last read and writes out
  * the same way.  You can change this behavior by modifying the
  * WriteAsAbsolutePath() flag.
  */
class FilePathClass
{
protected:
    /** The complete path: format is "<directory>/<filename>.<extension>" where /
      * is last slash and . is the first dot after the last slash */
    std::string _path;

    /** Controls how the Path is written out when WritePathString is called
      * Defaults to false */
    bool _writeAsAbsolutePath;

public:
    /** Constructor. Path() is initially "" and invalid */
    GLS_EXPORT FilePathClass();
    /** Implicit conversion - Path() is set to stringPath */
    GLS_EXPORT FilePathClass( const std::string& stringPath );
    GLS_EXPORT FilePathClass( const char* stringPath );

    /** Return true if the path points to a directory or file that COULD exist 
      * (i.e. Path() will return a valid path as close as we can verify it.)*/
    GLS_EXPORT bool IsValid() const;

    /** Return a string containing the characters that invalid to use in a path */
    static GLS_EXPORT const std::string& InvalidPathChars();

    /** Return true if this file path references a file that exists.
      * Applies only to files; returns false for directories.
      * Returns true for symbolic links that exist, regardless whether the link's target exists.
      */
    GLS_EXPORT bool FileExists() const;

    /** Return true if the Directory() of this path DOES exist */
    // Not Implemented
    //GLS_EXPORT bool DirectoryExists() const;

    /** Create the Directory() for this path if it doesn't exist
      * \return true if the directory exists
      * \return false if there was an error creating the directory */
    // Not Implemented
    //GLS_EXPORT bool CreateDirectory() const;

    /** Return a string containing the relative path
      * to this path from the given path's Directory
      * Returns Path() if the relative path cannot be determined */
    GLS_EXPORT std::string PathRelativeTo( const FilePathClass& basePath ) const;

    /** Return a string containing the complete path
      * \note this method returns whatever is stored
      * in the path whether it is valid or not */
    const std::string& Path() const { return _path; }

    /** Get the directory containing the referenced file (includes trailing slash)
      * "" if the Path is not valid */
    GLS_EXPORT std::string Directory() const;

    /** Get the filename of the file (including the extension)
      * "" if the Path is not valid or doesn't reference a file */
    GLS_EXPORT std::string FileName() const;

    /** Get the file extension for the file (everything after the last ".")
      * "" if the Path is not valid, doesn't reference a file, or the file has no extension */
    GLS_EXPORT std::string FileExtension() const;

    /** Replace the current file extension with the specified string.
      * This will also insert a '.' into the filename if needed.
      * \param ext The new extension (e.g. "txt")
      */
    GLS_EXPORT void FileExtension( const std::string& ext );

    /** Equality operators
      * If paths are equal they reference the same file
      * If paths are not equal it doesn't guarantee that they reference different files */
    GLS_EXPORT bool operator==( const FilePathClass& path ) const;
    inline bool     operator!=( const FilePathClass& path ) const { return !( *this == path ); }

    friend std::ostream& operator<<( std::ostream& outstr, const FilePathClass& path )
    {
        outstr << path.Path();
        return outstr;
    }

    friend std::istream& operator>>( std::istream& instr, FilePathClass& path )
    {
        instr >> path._path;
        return instr;
    }

    /** Assignment operator (absolute path) */
    GLS_EXPORT FilePathClass& operator=( const FilePathClass& path );

    /** Set this object to point to the current working directory 
      * \return true on success, false if there was an error */
    GLS_EXPORT bool SetToCWD();

    /** return true if the given string contains an absolute path */
    static GLS_EXPORT bool StringIsAbsolutePath( const std::string& strPath );

    /** return true if the given string contains an relative path */
    static GLS_EXPORT bool StringIsRelativePath( const std::string& strPath );

    /** return true if the given string contains a valid or absolute path as close as we can verify it */
    static GLS_EXPORT bool StringIsValidPath( const std::string& strPath );

    /** Get and set the WriteAsAbsolutePath flag */
    inline void WriteAsAbsolutePath( bool value ) { _writeAsAbsolutePath = value; }
    inline bool WriteAsAbsolutePath() { return _writeAsAbsolutePath; }

    /** Read a relative or absolute path from a string
      * \pre None
      * \post If strPath was an absolute path or invalid then this path will be set to strPath and WriteAsAbsolutePath() will be true
      *       If strPath was relative, this path will be set to basePath + strPath and WriteAsAbsolutePath() will be false
      * \param basePath Used to build a complete path if strPath contains a relative path
      * \param strPath The string to read into
      * \returns true on success or false if there was an error (basePath or strPath are invalid)
      */
    GLS_EXPORT bool ReadPathString( const FilePathClass& basePath, const std::string& strPath );

    /** Get the path string to write to a file
      * This strPath will be either the absolute or relative path depending
      * on the current setting of the WriteAsAbsolutePath() flag
      * \param basePath Used to build a relative path if WriteAsAbsolutePath is false
      * \param strPath The string to write to   
      */
    GLS_EXPORT void WritePathString( const FilePathClass& basePath, std::string* strPath );
};

/** Attribute for reading and writing FilePathClass objects as a clear string. */
class DistiAttributeFilePathClass : public DistiAttributeBase
{
protected:
    FilePathClass*               _attribPtr;        // Pointer to the actual storage location
    FilePathClass                _localStoragePath; // only used by local storage constructor
    const FilePathClass&         _basePath;         // Used for reading relative paths
    bool                         _useEmptyTag;      /**< true to use _emptyTag when writing path with WriteValue() if path does not have a filename */
    static GLS_EXPORT const char _emptyTag[];

public:
    /** This constructor has the storage external 
      * \param basePath
      * \param callback
      * \param name
      * \param attribPtr
      * \param useEmptyTag [optional, defaults to false]  true to use _emptyTag when writing path with WriteValue()
      *                    if path does not have a filename
      */
    GLS_EXPORT DistiAttributeFilePathClass( const FilePathClass& basePath, CallbackMethodCallerBase* callback, const AttributeName& name, FilePathClass* attribPtr, bool useEmptyTag = false )
        : DistiAttributeBase( callback, name, false )
        , _attribPtr( attribPtr )
        , _basePath( basePath )
        , _useEmptyTag( useEmptyTag )
    {
    }

    /** Creates local storage, and will resize as needed
      * \param basePath
      * \param callback
      * \param name
      * \param initialValue
      * \param useEmptyTag [optional, defaults to false]  true to use _emptyTag when writing path with WriteValue()
      *                    if path does not have a filename
      */
    GLS_EXPORT DistiAttributeFilePathClass( const FilePathClass& basePath, CallbackMethodCallerBase* callback, const AttributeName& name, FilePathClass initialValue, bool useEmptyTag = false )
        : DistiAttributeBase( callback, name, true )
        , _attribPtr( &_localStoragePath )
        , _localStoragePath( initialValue )
        , _basePath( basePath )
        , _useEmptyTag( useEmptyTag )
    {
    }

    static const char* GetEmptyTag() { return _emptyTag; }

    virtual GLS_EXPORT DistiAttributeBase& operator=( const DistiAttributeBase& oldClass )
    {
        const DistiAttributeFilePathClass* ptr;
        ptr = dynamic_cast<const DistiAttributeFilePathClass*>( &oldClass );
        if( ptr )
        {
            *_attribPtr = *( ptr->_attribPtr );
            CallCallback();
        }
        else
        {
            return DistiAttributeBase::operator=( oldClass );
        }
        return *this;
    }

    virtual GLS_EXPORT std::ostream& WriteValue( std::ostream& outstr )
    {
        if( _attribPtr )
        {
            std::string strPath;

            if( _useEmptyTag && _attribPtr->FileName().empty() )
            {
                strPath = _emptyTag;
            }
            else
            {
                _attribPtr->WritePathString( _basePath, &strPath );
            }

            outstr << strPath;
        }

        return outstr;
    }
    virtual GLS_EXPORT std::istream& ReadValue( std::istream& instr )
    {
        std::string strPath;
        GetToEnd( instr, strPath, true );

        if( _attribPtr )
        {
            // We have to always check for the empty tag
            // for any backward compatability
            if( strPath == _emptyTag )
            {
                strPath = "";
            }

            _attribPtr->ReadPathString( _basePath, strPath );
            CallCallback();
        }

        return instr;
    }
};

/** This is a FilePathClass attribute that will save/read the path relative to the current working directory. */
class DistiAttributeCWDRelativePath : public DistiAttributeFilePathClass
{
    FilePathClass _parentDocumentPath; // The parent document path, this is updated when we read and write
public:
    /** This constructor has the storage external */
    GLS_EXPORT DistiAttributeCWDRelativePath( CallbackMethodCallerBase* callback, const AttributeName& name, FilePathClass* attribPtr, bool useEmptyTag = false )
        : DistiAttributeFilePathClass( _parentDocumentPath, callback, name, attribPtr, useEmptyTag )
    {
    }

    /** Creates local storage, and will resize as needed */
    GLS_EXPORT DistiAttributeCWDRelativePath( CallbackMethodCallerBase* callback, const AttributeName& name, FilePathClass initialValue, bool useEmptyTag = false )
        : DistiAttributeFilePathClass( _parentDocumentPath, callback, name, initialValue, useEmptyTag )
    {
    }

    virtual GLS_EXPORT std::ostream& WriteValue( std::ostream& outstr )
    {
        // update base path
        _parentDocumentPath.SetToCWD();

        // write value as normal
        return DistiAttributeFilePathClass::WriteValue( outstr );
    }
    virtual GLS_EXPORT std::istream& ReadValue( std::istream& instr )
    {
        // update base path
        _parentDocumentPath.SetToCWD();

        // read value as normal
        return DistiAttributeFilePathClass::ReadValue( instr );
    }
};

} // end namespace disti

#endif //_PATH_CLASS_H