diff --git a/CHANGELOG.md b/CHANGELOG.md index f05125f..159be9a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Exposed "sago::internal::getHome()". It might be useful when converting from old file placement. ### Changed - - Tested and supports newer versions of CMake + - Now supports newer versions of CMake ## [4.2.0] 2022-02-06 @@ -44,7 +44,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Now requires a C++11 compatible compiler (was C++98) - Minimum Windows version raised from Windows XP to Windows 7. - The Mac version no longer depends on CoreServices - - The XDG implementation are slightly more resilient to unrelated environments in user-dirs.dirs + - The XDG implementation is slightly more resilient to unrelated environments in user-dirs.dirs - Improved CMake system ### Removed @@ -68,7 +68,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - Appveyor CI integration (Thanks @sum01) ### Changed - - Optimised use of iterator. + - Optimized use of iterators. - No longer keeps empty data structure on Mac and Windows platforms. ## [3.0] 2016-10-08 @@ -93,7 +93,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [2.0] 2015-10-26 ### Added -- Mac OS X support using Core Framework +- Mac OS X support using CoreServices Framework ## [1.0] 2015-09-21 Designed to work with Linux and Windows XP+ diff --git a/README.md b/README.md index e988ad5..0df838c 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ A C++ library to look for directories like `My Documents`, `~/.config`, `%APPDAT There are a lot of platform abstraction libraries available. You can get graphics abstraction libraries, GUI abstraction libraries and file abstraction libraries. But folder abstraction seems to be more difficult. -My problem was that the code that found the place to save data was platform dependent. This cluttered my code and often I would not discover that it did not compile until moving it to the different platforms. +My problem was that the code that found the place to save data was platform-dependent. This cluttered my code and often I would not discover that it did not compile until moving it to the different platforms. [I have written a bit more about it here.](https://sago007.blogspot.dk/2015/10/abstraction-for-special-folders.html) @@ -18,7 +18,7 @@ There are some alternatives that you might consider instead: * [QStandardPaths](https://doc.qt.io/qt-5/qstandardpaths.html) * [glib](https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html) -Both are properly more mature than this library. However they are both parts of large frameworks and using them with libraries outside the framework may not be that simple. +Both are probably more mature than this library. However they are both parts of large frameworks and using them with libraries outside the framework may not be that simple. ## Operating System Support @@ -34,9 +34,9 @@ It should work on any Unix system that has the following headers available: `pwd ### macOS -Version 4.0.0 and forward uses hardcoded values for the directories on Mac OS X. Unlike the other operating systems the folders cannot be moved on a Mac and the translation is done in the UI. -The versions 2.X and 3.X uses the deprecated FSFindFolder, which requires the CoreServices framework during linking. -Version 1.X simple used the XDG specification. +Version 4.0.0 and onwards use hardcoded values for the directories on Mac OS X. Unlike the other operating systems the folders cannot be moved on a Mac and the translation is done in the UI. +The versions 2.X and 3.X use the deprecated FSFindFolder, which requires the CoreServices framework during linking. +Version 1.X simply used the XDG specification. ## Usage @@ -173,6 +173,6 @@ From version 3.0, Windows always encodes to UTF-8, and this will be the default Before version 3.0, Windows was encoded in ANSI. Although the user may use any characters they want, I recommend that the program should have only ASCII characters in the source code itself. -# Licence +# License Provided under the MIT license for the same reason XDG is licensed under it. So that you can quickly copy-paste the methods you need or just include the "sago"-folder. diff --git a/sago/platform_folders.h b/sago/platform_folders.h index b4ada6c..908147d 100644 --- a/sago/platform_folders.h +++ b/sago/platform_folders.h @@ -1,5 +1,5 @@ /* -Its is under the MIT license, to encourage reuse by cut-and-paste. +It is under the MIT license, to encourage reuse by cut-and-paste. The original files are hosted here: https://github.com/sago007/PlatformFolders @@ -33,7 +33,7 @@ SOFTWARE. #include /** - * The namespace I use for common function. Nothing special about it. + * The namespace I use for common functions. Nothing special about it. */ namespace sago { @@ -52,7 +52,7 @@ std::string getHome(); #endif //DOXYGEN_SHOULD_SKIP_THIS /** - * Retrives the base folder for storing data files. + * Retrieves the base folder for storing data files. * You must add the program name yourself like this: * @code{.cpp} * string data_home = getDataHome()+"/My Program Name/"; @@ -64,7 +64,7 @@ std::string getHome(); std::string getDataHome(); /** - * Retrives the base folder for storing config files. + * Retrieves the base folder for storing config files. * You must add the program name yourself like this: * @code{.cpp} * string data_home = getConfigHome()+"/My Program Name/"; @@ -76,7 +76,7 @@ std::string getDataHome(); std::string getConfigHome(); /** - * Retrives the base folder for storing cache files. + * Retrieves the base folder for storing cache files. * You must add the program name yourself like this: * @code{.cpp} * string data_home = getCacheDir()+"/My Program Name/cache/"; @@ -89,7 +89,7 @@ std::string getConfigHome(); std::string getCacheDir(); /** - * Retrives the base folder used for state files. + * Retrieves the base folder used for state files. * You must add the program name yourself like this: * @code{.cpp} * string data_home = getStateDir()+"/My Program Name/"; @@ -97,19 +97,19 @@ std::string getCacheDir(); * On Windows this defaults to %APPDATALOCAL% * On Linux this defaults to ~/.local/state but can be configured by the user * On OS X this is the same as getDataHome() - * @return The base folder for storing data that do not need to be backed up but should not be reguarly deleted either. + * @return The base folder for storing data that do not need to be backed up but should not be regularly deleted either. */ std::string getStateDir(); /** * This will append extra folders that your program should be looking for data files in. - * This does not normally include the path returned by GetDataHome(). + * This does not normally include the path returned by getDataHome(). * If you want all the folders you should do something like: * @code{.cpp} * vector folders; * folders.push_back(getDataHome()); * appendAdditionalDataDirectories(folders); - * for (string s& : folders) { + * for (string& s : folders) { * s+="/My Program Name/"; * } * @endcode @@ -121,13 +121,13 @@ void appendAdditionalDataDirectories(std::vector& homes); /** * This will append extra folders that your program should be looking for config files in. - * This does not normally include the path returned by GetConfigHome(). + * This does not normally include the path returned by getConfigHome(). * If you want all the folders you should do something like: * @code{.cpp} * std::vector folders; * folders.push_back(sago::getConfigHome()); * sago::appendAdditionalConfigDirectories(folders); - * for (std::string s& : folders) { + * for (std::string& s : folders) { * s+="/My Program Name/"; * } * @endcode @@ -194,8 +194,8 @@ std::string getVideoFolder(); * string saved_games_folder = sago::getSaveGamesFolder1()+"/My Program Name/"; * @endcode * @note Windows: This is an XP compatible version and returns the path to "My Games" in Documents. Vista and later has an official folder. - * @note Linux: XDF does not define a folder for saved games. This will just return the same as GetDataHome() - * @return The folder base folder for storing save games. + * @note Linux: XDG does not define a folder for saved games. This will just return the same as getDataHome() + * @return The base folder for storing save games. */ std::string getSaveGamesFolder1(); @@ -205,18 +205,18 @@ std::string getSaveGamesFolder1(); * @code{.cpp} * string saved_games_folder = sago::getSaveGamesFolder2()+"/My Program Name/"; * @endcode - * @note PlatformFolders provide different folders to for saved games as not all operating systems has support for Saved Games yet. + * @note PlatformFolders provides different folders for saved games as not all operating systems has support for Saved Games yet. * It is recommended to pick the highest number (currently getSaveGamesFolder2) at the time your product enters production and stick with it * @note Windows: This returns the "Saved Games" folder. This folder exist in Vista and later - * @note Linux: XDF does not define a folder for saved games. This will just return the same as GetDataHome() - * @return The folder base folder for storing save games. + * @note Linux: XDG does not define a folder for saved games. This will just return the same as getDataHome() + * @return The base folder for storing save games. */ std::string getSaveGamesFolder2(); #ifndef DOXYGEN_SHOULD_SKIP_THIS /** - * This class contains methods for finding the system depended special folders. + * This class contains methods for finding the system-dependent special folders. * For Windows these folders are either by convention or given by CSIDL. * For Linux XDG convention is used. * The Linux version has very little error checking and assumes that the config is correct @@ -269,8 +269,8 @@ public: * string saved_games_folder = pf.getSaveGamesFolder1()+"/My Program Name/"; * @endcode * @note Windows: This is an XP compatible version and returns the path to "My Games" in Documents. Vista and later has an official folder. - * @note Linux: XDF does not define a folder for saved games. This will just return the same as GetDataHome() - * @return The folder base folder for storing save games. + * @note Linux: XDG does not define a folder for saved games. This will just return the same as getDataHome() + * @return The base folder for storing save games. */ std::string getSaveGamesFolder1() const; private: