GL Studio C++ Runtime API
file_path_class.h
Go to the documentation of this file.
1/// \file file_path_class.h
2/// \brief A class to handle file paths.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2017 by The DiSTI Corporation.<br>
7/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<br>
9/// USA<br>
10/// <br>
11/// All rights reserved.<br>
12///
13/// This Software contains proprietary trade secrets of DiSTI and may not be
14/// reproduced, in whole or part, in any form, or by any means of electronic,
15/// mechanical, or otherwise, without the written permission of DiSTI. Said
16/// permission may be derived through the purchase of applicable DiSTI product
17/// licenses which detail the distribution rights of this content and any
18/// Derivative Works based on this or other copyrighted DiSTI Software.
19///
20/// NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21/// AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22/// PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23/// AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24/// IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25/// PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26///
27/// LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28/// IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29/// INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30/// DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31/// INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32/// INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33/// OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34/// EXCEED FIVE DOLLARS (US$5.00).
35///
36/// The aforementioned terms and restrictions are governed by the laws of the
37/// State of Florida and the United States of America.
38
39#ifndef INCLUDED_DISTI_FILE_PATH_CLASS_H
40#define INCLUDED_DISTI_FILE_PATH_CLASS_H
41
42#include "disti_metadata.h"
44#include "util.h" // This is glstudio specific
45#include <fstream>
46#include <string>
47
48namespace disti
49{
50/** \class FilePathClass
51 *
52 * The FilePathClass represents a single absolute path.
53 * There are methods for getting the directory, filename,
54 * file extension, and checking the validity of the path.
55 * You can get a relative path string by comparing two FilePathClass objects.
56 * FilePathClass also has methods for reading/writing absolute or relative
57 * path strings, the class remembers which was last read and writes out
58 * the same way. You can change this behavior by modifying the
59 * WriteAsAbsolutePath() flag.
60 */
62{
63protected:
64 /** The complete path: format is "<directory>/<filename>.<extension>" where /
65 * is last slash and . is the first dot after the last slash */
66 std::string _path;
67
68 /** Controls how the Path is written out when WritePathString is called
69 * Defaults to false */
71
72public:
73 /** Default construction. Path() is initially "" and invalid */
75
76 /// Implicit conversion
77 /// \param stringPath The path to set.
78 GLS_EXPORT FilePathClass( const std::string& stringPath );
79
80 /// Implicit conversion
81 /// \param stringPath The path to set.
82 GLS_EXPORT FilePathClass( const char* stringPath );
83
84 /// Copy construction
85 /// \param other The object to copy from.
87 {
88 *this = other;
89 }
90
91 /// Copy assignment
92 /// \param other The object to copy from.
93 /// \return The resulting object (this).
95 {
96 if( this != &other )
97 {
98 _path = other._path;
100 }
101 return *this;
102 }
103
104#if defined( DISTI_HAS_RVAL_REFS )
105 /// Move construction
106 /// \param other The object to move from.
108 {
109 *this = std::move( other );
110 }
111
112 /// Move assignment
113 /// \param other The object to move from.
114 /// \return The resulting object (this).
116 {
117 if( this != &other )
118 {
119 _path = std::move( other._path );
120 _writeAsAbsolutePath = other._writeAsAbsolutePath;
121 }
122 return *this;
123 }
124#endif
125
126 /// \return True if the path points to a directory or file that COULD exist.
127 /// (i.e. Path() will return a valid path as close as we can verify it.)
128 GLS_EXPORT bool IsValid() const;
129
130 /// \return A string containing the characters that invalid to use in a path.
131 static GLS_EXPORT const std::string& InvalidPathChars();
132
133 /// \return True if this file path references a file that exists.
134 /// \note Applies only to files; returns false for directories.
135 /// Returns true for symbolic links that exist, regardless whether the link's target exists.
136 GLS_EXPORT bool FileExists() const;
137
138 /// \param basePath The path to calculate the relative path from.
139 /// \return A string containing the relative path to this path from the given path's directory.
140 /// \note Returns Path() if the relative path cannot be determined.
141 GLS_EXPORT std::string PathRelativeTo( const FilePathClass& basePath ) const;
142
143 /// \return A string containing the complete path.
144 /// \note This method returns whatever is stored in the path whether it is valid or not.
145 const std::string& Path() const { return _path; }
146
147 /// \return The directory containing the referenced file (includes trailing slash) or "" if the path is not valid.
148 GLS_EXPORT std::string Directory() const;
149
150 /// \return The filename of the file (including the extension) or "" if the path is not valid or doesn't reference a file.
151 GLS_EXPORT std::string FileName() const;
152
153 /// \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.
154 GLS_EXPORT std::string FileExtension() const;
155
156 /// Replace the current file extension with the specified string.
157 /// This will also insert a '.' into the filename if needed.
158 /// \param ext The new extension (e.g. "txt")
159 GLS_EXPORT void FileExtension( const std::string& ext );
160
161 /// Equality operator
162 /// If paths are equal they reference the same file.
163 /// \param path The path to compare.
164 /// \return Whether or not the paths are equal.
165 GLS_EXPORT bool operator==( const FilePathClass& path ) const;
166
167 /// Inequality operator
168 /// If paths are not equal it doesn't guarantee that they reference different files.
169 /// \param path The path to compare.
170 /// \return Whether or not the paths are not equal.
171 bool operator!=( const FilePathClass& path ) const { return !( *this == path ); }
172
173 /// Stream out operator
174 /// \param outstr Stream to write path to.
175 /// \param path Path to write to the stream.
176 /// \return The stream in its current state.
177 friend std::ostream& operator<<( std::ostream& outstr, const FilePathClass& path )
178 {
179 outstr << path.Path();
180 return outstr;
181 }
182
183 /// Stream in operator
184 /// \param instr The stream to read path from.
185 /// \param path Returned path read from the stream.
186 /// \return The stream in its current state.
187 friend std::istream& operator>>( std::istream& instr, FilePathClass& path )
188 {
189 instr >> path._path;
190 return instr;
191 }
192
193 /** Set this object to point to the current working directory
194 * \return true on success, false if there was an error */
196
197 /// \return A file path set to the current working directory.
199 {
200 FilePathClass path;
201 path.SetToCWD();
202 return path;
203 }
204
205 /// \param strPath The string to check.
206 /// \return true If the given string contains an absolute path.
207 static GLS_EXPORT bool StringIsAbsolutePath( const std::string& strPath );
208
209 /// \param strPath The string to check.
210 /// \return True if the given string contains an relative path.
211 static GLS_EXPORT bool StringIsRelativePath( const std::string& strPath );
212
213 /// \param strPath The string to check.
214 /// \return true If the given string contains a valid or absolute path as close as we can verify it.
215 static GLS_EXPORT bool StringIsValidPath( const std::string& strPath );
216
217 /// Set whether or not paths will be written as absolute paths.
218 /// \param value The new path write value to set.
219 void WriteAsAbsolutePath( bool value ) { _writeAsAbsolutePath = value; }
220
221 /// \return Whether or not paths will be written as absolute.
223
224 /** Read a relative or absolute path from a string
225 * \pre None
226 * \post If strPath was an absolute path or invalid then this path will be set to strPath and WriteAsAbsolutePath() will be true
227 * If strPath was relative, this path will be set to basePath + strPath and WriteAsAbsolutePath() will be false
228 * \param basePath Used to build a complete path if strPath contains a relative path
229 * \param strPath The string to read into
230 * \returns true on success or false if there was an error (basePath or strPath are invalid)
231 */
232 GLS_EXPORT bool ReadPathString( const FilePathClass& basePath, const std::string& strPath );
233
234 /** Get the path string to write to a file
235 * This strPath will be either the absolute or relative path depending
236 * on the current setting of the WriteAsAbsolutePath() flag
237 * \param basePath Used to build a relative path if WriteAsAbsolutePath is false
238 * \param strPath The string to write to
239 */
240 GLS_EXPORT void WritePathString( const FilePathClass& basePath, std::string* strPath );
241};
242
243/** Attribute for reading and writing FilePathClass objects as a clear string. */
245{
246protected:
247 FilePathClass* _attribPtr; ///< Pointer to the actual storage location.
248 FilePathClass _localStoragePath; ///< Only used by local storage constructor.
249 const FilePathClass& _basePath; ///< Used for reading relative paths.
250 bool _useEmptyTag; ///< true to use _emptyTag when writing path with WriteValue() if path does not have a filename.
251 static GLS_EXPORT const char _emptyTag[]; ///< Backing storage for the string used to represent empty paths.
252
253public:
254 /// This constructor has the storage external.
255 /// \param basePath
256 /// \param callback
257 /// \param name
258 /// \param attribPtr
259 /// \param useEmptyTag [optional, defaults to false] true to use _emptyTag when writing path with WriteValue()
260 /// if path does not have a filename
261 DistiAttributeFilePathClass( const FilePathClass& basePath, CallbackMethodCallerBase* callback, const AttributeName& name, FilePathClass* attribPtr, bool useEmptyTag = false )
262 : DistiAttributeBase( callback, name, false )
263 , _attribPtr( attribPtr )
264 , _basePath( basePath )
265 , _useEmptyTag( useEmptyTag )
266 {
267 }
268
269 /// Creates local storage, and will resize as needed.
270 /// \param basePath
271 /// \param callback
272 /// \param name
273 /// \param initialValue
274 /// \param useEmptyTag [optional, defaults to false] true to use _emptyTag when writing path with WriteValue()
275 /// if path does not have a filename
276 DistiAttributeFilePathClass( const FilePathClass& basePath, CallbackMethodCallerBase* callback, const AttributeName& name, FilePathClass initialValue, bool useEmptyTag = false )
277 : DistiAttributeBase( callback, name, true )
279 , _localStoragePath( initialValue )
280 , _basePath( basePath )
281 , _useEmptyTag( useEmptyTag )
282 {
283 }
284
285 /// \return The string value used to represent an empty path.
286 static const char* GetEmptyTag() { return _emptyTag; }
287
289 {
291 ptr = dynamic_cast<const DistiAttributeFilePathClass*>( &oldClass );
292 if( ptr )
293 {
294 *_attribPtr = *( ptr->_attribPtr );
295 CallCallback();
296 }
297 else
298 {
299 return DistiAttributeBase::operator=( oldClass );
300 }
301 return *this;
302 }
303
304 std::ostream& WriteValue( std::ostream& outstr ) DISTI_METHOD_OVERRIDE
305 {
306 if( _attribPtr )
307 {
308 std::string strPath;
309
310 if( _useEmptyTag && _attribPtr->FileName().empty() )
311 {
312 strPath = _emptyTag;
313 }
314 else
315 {
317 }
318
319 outstr << strPath;
320 }
321
322 return outstr;
323 }
324
325 std::istream& ReadValue( std::istream& instr ) DISTI_METHOD_OVERRIDE
326 {
327 std::string strPath;
328 GetToEnd( instr, strPath, true );
329
330 if( _attribPtr )
331 {
332 // We have to always check for the empty tag
333 // for any backward compatability
334 if( strPath == _emptyTag )
335 {
336 strPath = "";
337 }
338
340 CallCallback();
341 }
342
343 return instr;
344 }
345
346 std::string Type() const DISTI_METHOD_OVERRIDE
347 {
348 return Demangle<FilePathClass>();
349 }
350};
351
352/** This is a FilePathClass attribute that will save/read the path relative to the current working directory. */
354{
355 FilePathClass _parentDocumentPath; ///< The parent document path, this is updated when we read and write.
356public:
357 /// This constructor has the storage external.
358 /// \param callback
359 /// \param name
360 /// \param attribPtr
361 /// \param useEmptyTag [optional, defaults to false] true to use _emptyTag when writing path with WriteValue()
362 /// if path does not have a filename
363 DistiAttributeCWDRelativePath( CallbackMethodCallerBase* callback, const AttributeName& name, FilePathClass* attribPtr, bool useEmptyTag = false )
364 : DistiAttributeFilePathClass( _parentDocumentPath, callback, name, attribPtr, useEmptyTag )
365 {
366 }
367
368 /// Creates local storage, and will resize as needed.
369 /// \param callback
370 /// \param name
371 /// \param initialValue
372 /// \param useEmptyTag [optional, defaults to false] true to use _emptyTag when writing path with WriteValue()
373 /// if path does not have a filename
374 DistiAttributeCWDRelativePath( CallbackMethodCallerBase* callback, const AttributeName& name, FilePathClass initialValue, bool useEmptyTag = false )
375 : DistiAttributeFilePathClass( _parentDocumentPath, callback, name, initialValue, useEmptyTag )
376 {
377 }
378
379 std::ostream& WriteValue( std::ostream& outstr ) DISTI_METHOD_OVERRIDE
380 {
381 // update base path
382 _parentDocumentPath.SetToCWD();
383
384 // write value as normal
386 }
387
388 std::istream& ReadValue( std::istream& instr ) DISTI_METHOD_OVERRIDE
389 {
390 // update base path
391 _parentDocumentPath.SetToCWD();
392
393 // read value as normal
395 }
396
397 std::string Type() const DISTI_METHOD_OVERRIDE
398 {
399 return Demangle<FilePathClass>();
400 }
401};
402
403} // end namespace disti
404
405#endif //_PATH_CLASS_H
Definition: disti_metadata.h:87
Definition: callback_caller_base.h:55
Definition: disti_metadata.h:220
virtual void CallCallback()
Calls callback CallType3 if it has been set.
virtual DistiAttributeBase & operator=(const DistiAttributeBase &oldClass)
Definition: file_path_class.h:354
std::istream & ReadValue(std::istream &instr) override
Definition: file_path_class.h:388
std::string Type() const override
Definition: file_path_class.h:397
std::ostream & WriteValue(std::ostream &outstr) override
Definition: file_path_class.h:379
DistiAttributeCWDRelativePath(CallbackMethodCallerBase *callback, const AttributeName &name, FilePathClass *attribPtr, bool useEmptyTag=false)
Definition: file_path_class.h:363
DistiAttributeCWDRelativePath(CallbackMethodCallerBase *callback, const AttributeName &name, FilePathClass initialValue, bool useEmptyTag=false)
Definition: file_path_class.h:374
Definition: file_path_class.h:245
static const char * GetEmptyTag()
Definition: file_path_class.h:286
DistiAttributeFilePathClass(const FilePathClass &basePath, CallbackMethodCallerBase *callback, const AttributeName &name, FilePathClass initialValue, bool useEmptyTag=false)
Definition: file_path_class.h:276
static const char _emptyTag[]
Backing storage for the string used to represent empty paths.
Definition: file_path_class.h:251
FilePathClass * _attribPtr
Pointer to the actual storage location.
Definition: file_path_class.h:247
std::istream & ReadValue(std::istream &instr) override
Definition: file_path_class.h:325
std::string Type() const override
Definition: file_path_class.h:346
std::ostream & WriteValue(std::ostream &outstr) override
Definition: file_path_class.h:304
DistiAttributeFilePathClass(const FilePathClass &basePath, CallbackMethodCallerBase *callback, const AttributeName &name, FilePathClass *attribPtr, bool useEmptyTag=false)
Definition: file_path_class.h:261
DistiAttributeBase & operator=(const DistiAttributeBase &oldClass) override
Definition: file_path_class.h:288
const FilePathClass & _basePath
Used for reading relative paths.
Definition: file_path_class.h:249
bool _useEmptyTag
true to use _emptyTag when writing path with WriteValue() if path does not have a filename.
Definition: file_path_class.h:250
FilePathClass _localStoragePath
Only used by local storage constructor.
Definition: file_path_class.h:248
Definition: file_path_class.h:62
static const std::string & InvalidPathChars()
void WriteAsAbsolutePath(bool value)
Definition: file_path_class.h:219
std::string _path
Definition: file_path_class.h:66
FilePathClass & operator=(const FilePathClass &other)
Definition: file_path_class.h:94
static bool StringIsRelativePath(const std::string &strPath)
std::string Directory() const
static bool StringIsAbsolutePath(const std::string &strPath)
std::string FileName() const
bool _writeAsAbsolutePath
Definition: file_path_class.h:70
bool operator==(const FilePathClass &path) const
void FileExtension(const std::string &ext)
std::string PathRelativeTo(const FilePathClass &basePath) const
bool FileExists() const
static FilePathClass GetCWD()
Definition: file_path_class.h:198
FilePathClass(const std::string &stringPath)
FilePathClass & operator=(FilePathClass &&other)
Definition: file_path_class.h:115
friend std::istream & operator>>(std::istream &instr, FilePathClass &path)
Definition: file_path_class.h:187
bool operator!=(const FilePathClass &path) const
Definition: file_path_class.h:171
FilePathClass(FilePathClass &&other)
Definition: file_path_class.h:107
static bool StringIsValidPath(const std::string &strPath)
bool ReadPathString(const FilePathClass &basePath, const std::string &strPath)
bool IsValid() const
void WritePathString(const FilePathClass &basePath, std::string *strPath)
const std::string & Path() const
Definition: file_path_class.h:145
bool WriteAsAbsolutePath()
Definition: file_path_class.h:222
FilePathClass(const FilePathClass &other)
Definition: file_path_class.h:86
FilePathClass(const char *stringPath)
std::string FileExtension() const
friend std::ostream & operator<<(std::ostream &outstr, const FilePathClass &path)
Definition: file_path_class.h:177
The disti metadata.
Macros and helper code to determine what subset of C++11/14/17 is available.
#define DISTI_METHOD_OVERRIDE
Macro to wrap the override keyword, removed on compilers that don't support it.
Definition: gls_cpp_lang_support.h:221
#define DISTI_FUNC_NOEXCEPT
Macro to wrap the noexcept keyword, removed on compilers that don't support it.
Definition: gls_cpp_lang_support.h:239
#define GLS_EXPORT
Macro denoting which functions should be visible from the runtime library.
Definition: gls_include.h:50
Definition: bmpimage.h:46
bool GetToEnd(std::istream &instr, std::string &result, bool decode)
Generally useful defines, macros, enumerations and function prototypes.