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_DISTI_FILE_PATH_CLASS_H
#define INCLUDED_DISTI_FILE_PATH_CLASS_H
 
#include "disti_metadata.h"
#include "gls_cpp_lang_support.h"
#include "util.h" // This is glstudio specific
#include <fstream>
#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:
    /** Default construction. Path() is initially "" and invalid */
    GLS_EXPORT FilePathClass();
 
    /// Implicit conversion
    /// \param stringPath The path to set.
    GLS_EXPORT FilePathClass( const std::string& stringPath );
 
    /// Implicit conversion
    /// \param stringPath The path to set.
    GLS_EXPORT FilePathClass( const char* stringPath );
 
    /// Copy construction
    /// \param other The object to copy from.
    GLS_EXPORT FilePathClass( const FilePathClass& other )
    {
        *this = other;
    }
 
    /// Copy assignment
    /// \param other The object to copy from.
    /// \return The resulting object (this).
    GLS_EXPORT FilePathClass& operator=( const FilePathClass& other )
    {
        if( this != &other )
        {
            _path                = other._path;
            _writeAsAbsolutePath = other._writeAsAbsolutePath;
        }
        return *this;
    }
 
#if defined( DISTI_HAS_RVAL_REFS )
    /// Move construction
    /// \param other The object to move from.
    FilePathClass( FilePathClass&& other )
    {
        *this = std::move( other );
    }
 
    /// Move assignment
    /// \param other The object to move from.
    /// \return The resulting object (this).
    FilePathClass& operator=( FilePathClass&& other )
    {
        if( this != &other )
        {
            _path                = std::move( other._path );
            _writeAsAbsolutePath = other._writeAsAbsolutePath;
        }
        return *this;
    }
#endif
 
    /// \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.
    /// \note 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;
 
    /// \param basePath The path to calculate the relative path from.
    /// \return A string containing the relative path to this path from the given path's directory.
    /// \note 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; }
 
    /// \return The directory containing the referenced file (includes trailing slash) or "" if the path is not valid.
    GLS_EXPORT std::string Directory() const;
 
    /// \return The filename of the file (including the extension) or "" if the path is not valid or doesn't reference a file.
    GLS_EXPORT std::string FileName() const;
 
    /// \return The file extension for the file (everything after the last ".") or "" 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 operator
    /// If paths are equal they reference the same file.
    /// \param path The path to compare.
    /// \return Whether or not the paths are equal.
    GLS_EXPORT bool operator==( const FilePathClass& path ) const;
 
    /// Inequality operator
    /// If paths are not equal it doesn't guarantee that they reference different files.
    /// \param path The path to compare.
    /// \return Whether or not the paths are not equal.
    inline bool operator!=( const FilePathClass& path ) const { return !( *this == path ); }
 
    /// Stream out operator
    /// \param outstr Stream to write path to.
    /// \param path Path to write to the stream.
    /// \return The stream in its current state.
    friend std::ostream& operator<<( std::ostream& outstr, const FilePathClass& path )
    {
        outstr << path.Path();
        return outstr;
    }
 
    /// Stream in operator
    /// \param instr The stream to read path from.
    /// \param path Returned path read from the stream.
    /// \return The stream in its current state.
    friend std::istream& operator>>( std::istream& instr, FilePathClass& path )
    {
        instr >> path._path;
        return instr;
    }
 
    /** 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 A file path set to the current working directory.
    static GLS_EXPORT FilePathClass GetCWD()
    {
        FilePathClass path;
        path.SetToCWD();
        return path;
    }
 
    /// \param strPath The string to check.
    /// \return true If the given string contains an absolute path.
    static GLS_EXPORT bool StringIsAbsolutePath( const std::string& strPath );
 
    /// \param strPath The string to check.
    /// \return True if the given string contains an relative path.
    static GLS_EXPORT bool StringIsRelativePath( const std::string& strPath );
 
    /// \param strPath The string to check.
    /// \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 );
 
    /// Set whether or not paths will be written as absolute paths.
    /// \param value The new path write value to set.
    inline void WriteAsAbsolutePath( bool value ) { _writeAsAbsolutePath = value; }
 
    /// \return Whether or not paths will be written as absolute.
    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[];       ///< Backing storage for the string used to represent empty paths.
 
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 )
    {
    }
 
    /// \return The string value used to represent an empty path.
    static const char* GetEmptyTag() { return _emptyTag; }
 
    virtual GLS_EXPORT DistiAttributeBase& operator=( const DistiAttributeBase& oldClass ) DISTI_METHOD_OVERRIDE
    {
        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 ) DISTI_METHOD_OVERRIDE
    {
        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 ) DISTI_METHOD_OVERRIDE
    {
        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.
    /// \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 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.
    /// \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 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 ) DISTI_METHOD_OVERRIDE
    {
        // update base path
        _parentDocumentPath.SetToCWD();
 
        // write value as normal
        return DistiAttributeFilePathClass::WriteValue( outstr );
    }
 
    virtual GLS_EXPORT std::istream& ReadValue( std::istream& instr ) DISTI_METHOD_OVERRIDE
    {
        // update base path
        _parentDocumentPath.SetToCWD();
 
        // read value as normal
        return DistiAttributeFilePathClass::ReadValue( instr );
    }
};
 
} // end namespace disti
 
#endif //_PATH_CLASS_H