flag --stderr and exit messages (#229)

- emit signals
- path operations from config.cpp moved to pathtools.cpp
- tests fixed and extended
- documentation updated

Author: Gemba

docs/CLIHELP.md

@@ -847,6 +847,32 @@ Skyscraper -p snes --cache edit --startat "rom name.zip"
 Skyscraper -p snes -s thegamesdb --startat "relative/path/to/rom name.zip"
 ```
 
+### --stderr
+
+Prints a brief one-liner on `stderr` when Skyscraper ran into an error and exits with a non-zero return value. This is mainly useful when you call Skyscraper from another program. If you combine it with a redirect of `stdout` to `/dev/null` you can mute the general Skyscraper output. The format of the one-liner is: `Skyscraper: <cause>: <effect>`, thus it can be easily parsed by the calling program. Additionally, an exit code of 2 means some CLI parameter is wrong, an exit code of 1 is used by Skyscraper to signal other error conditions (with a `config.ini` setting or during runtime).
+
+**Example(s)**
+
+Try these in contrast to see the difference in output:
+
+```bash
+# Force an error condition.
+$ Skyscraper -p dontexist
+[...]
+$ Skyscraper --stderr -p dontexist
+[...]
+$ Skyscraper --stderr -p dontexist > /dev/null
+Skyscraper: ambigous platform parameter: Platform parameter missing or unknown platform provided
+$ echo $?        # returns 2 as platform is not valid
+
+# Assume input folder ~/RetroPie/roms/bbcmicro does not yet exist.
+# However, platform name is valid.
+```bash
+$ Skyscraper --stderr -p bbcmicro > /dev/null
+Skyscraper: cannot access '/home/pi/RetroPie/roms/bbcmicro': No such directory
+$ echo $?        # returns 1 as platform is valid but the input folder does not exist
+```
+
 ### --verbosity &lt;0-3&gt;
 
 Sets how verbose Skyscraper should be when running. Default level is 0. The higher the value, the more info Skyscraper will output to the terminal while running. Maximum value is 3. Consider setting this in [`config.ini`](CONFIGINI.md#verbosity) instead.

docs/CONFIGINI.md

@@ -447,7 +447,7 @@ Allowed in sections: `[main]`
 This option is _only_ applicable when also setting the `frontend="attractmode"` option. It sets the _emulator_ to be used when generating the `attractmode` game list. On RetroPie the emulator name is mostly the same as the platform.
 
 Default value: unset  
-Allowed in sections: `[main]`, `[<PLATFORM>]`, `[<FRONTEND>]`
+Allowed in sections: `[main]`, `[<PLATFORM>]` and frontend `[attractmode]`
 
 ---
 

skyscraper.pro

@@ -136,6 +136,7 @@ HEADERS += src/skyscraper.h \
            src/fxrotate.h \
            src/fxscanlines.h \
            src/nametools.h \
+           src/pathtools.h \
            src/queue.h
 
 SOURCES += src/main.cpp \
@@ -190,6 +191,7 @@ SOURCES += src/main.cpp \
            src/fxrotate.cpp \
            src/fxscanlines.cpp \
            src/nametools.cpp \
+           src/pathtools.cpp \
            src/queue.cpp
 
 SUBDIRS += \

src/abstractfrontend.cpp

@@ -25,8 +25,8 @@
 
 #include "abstractfrontend.h"
 
-#include "config.h"
 #include "gameentry.h"
+#include "pathtools.h"
 
 #include <QDebug>
 #include <QDir>
@@ -117,7 +117,7 @@ QString AbstractFrontend::getTargetFilePath(const GameEntry::Types t,
                               "maybe incomplete.";
             }
         }
-        fp = Config::lexicallyNormalPath(fp);
+        fp = PathTools::lexicallyNormalPath(fp);
     } else {
         fp = "";
     }

src/abstractfrontend.h

@@ -77,6 +77,9 @@ class AbstractFrontend : public QObject {
     bool copyMedia(GameEntry::Types &, const QString &, const QString &,
                    GameEntry &);
 
+signals:
+    void die(const int &, const QString &, const QString &);
+
 protected:
     virtual QString getTargetFileName(GameEntry::Types t,
                                       const QString &baseName) {

src/abstractscraper.cpp

@@ -733,16 +733,32 @@ QVector<int> AbstractScraper::getPlatformId(const QString) {
 QVariantMap AbstractScraper::readJson(const QString &filename) {
     QVariantMap m;
     QFile jsonFile(filename);
-    if (jsonFile.open(QIODevice::ReadOnly)) {
-        QJsonObject jsonObj =
-            QJsonDocument::fromJson(jsonFile.readAll()).object();
-        m = jsonObj.toVariantMap();
-        jsonFile.close();
-    } else {
-        printf("\033[1;31mFile '%s' not found. Please fix.\n\nNow "
-               "quitting...\033[0m\n",
+    QJsonObject jsonObj;
+    bool canRead = jsonFile.open(QIODevice::ReadOnly);
+    if (canRead) {
+        jsonObj = QJsonDocument::fromJson(jsonFile.readAll()).object();
+        if (!jsonObj.isEmpty()) {
+            m = jsonObj.toVariantMap();
+            jsonFile.close();
+        }
+    }
+    if (!canRead) {
+        printf("\033[1;31mFile '%s' not found or not readable. Please "
+               "fix.\nNot scraping...\n\033[0m",
+               filename.toUtf8().constData());
+    } else if (jsonObj.isEmpty()) {
+        printf("\033[1;31mFile '%s' has invalid JSON format. Please fix.\nNot "
+               "scraping...\n\033[0m",
                filename.toUtf8().constData());
-        exit(1);
     }
     return m;
+}
+
+void AbstractScraper::bury(const int &returnCode, const QString &effect,
+                           const QString &cause) {
+    if (config->stdErr) {
+        fprintf(stderr, "Skyscraper: %s: %s\n", effect.toStdString().c_str(),
+                cause.toStdString().c_str());
+    }
+    exit(returnCode);
 }

src/abstractscraper.h

@@ -64,6 +64,12 @@ class AbstractScraper : public QObject {
     void detectRegionFromFilename(const QFileInfo &info);
 #endif
 
+signals:
+    void die(const int &, const QString &, const QString &);
+
+public slots:
+    void bury(const int &, const QString &, const QString &);
+
 protected:
     Settings *config;
 

src/attractmode.cpp

@@ -25,9 +25,9 @@
 
 #include "attractmode.h"
 
-#include "config.h"
 #include "gameentry.h"
 #include "nametools.h"
+#include "pathtools.h"
 #include "strtools.h"
 
 #include <QDate>
@@ -211,7 +211,9 @@ void AttractMode::checkReqs() {
     if (config->frontendExtra.isEmpty()) {
         printf("Frontend 'attractmode' requires emulator set with '-e'. Check "
                "'--help' for more information.\n");
-        exit(0);
+        emit die(
+            1, "incomplete configuration",
+            "Frontend 'attractmode' requires '-e' or 'emulator=' to be set");
     }
     if (!config->frontendExtra.contains(".cfg")) {
         config->frontendExtra.append(".cfg");
@@ -230,19 +232,21 @@ void AttractMode::checkReqs() {
 
     printf("Looking for emulator cfg file:\n");
 
-    if (checkEmulatorFile(config->frontendExtra)) {
-        return;
-    }
-
     // For RetroPie this is linked directly to
     // /opt/retropie/configs/all/attractmode/emulators/
-    if (checkEmulatorFile(QDir::homePath() % "/.attract/emulators/" +
-                          config->frontendExtra)) {
+    QString altEmuFn =
+        QDir::homePath() % "/.attract/emulators/" % config->frontendExtra;
+    if (checkEmulatorFile(config->frontendExtra) ||
+        checkEmulatorFile(altEmuFn)) {
         return;
     }
 
     printf("Couldn't locate emulator cfg file, exiting...\n");
-    exit(1);
+    emit die(1,
+             QString("can neither access '%1' nor '%2")
+                 .arg(config->frontendExtra)
+                 .arg(altEmuFn),
+             "Files do not exist");
 }
 
 bool AttractMode::checkEmulatorFile(QString fileName) {
@@ -310,7 +314,7 @@ QString AttractMode::getVideosFolder() {
         mediaTypeFolder = getMediaTypeFolder("snap", true);
     }
     if (mediaTypeFolder.isEmpty()) {
-        mediaTypeFolder = Config::concatPath(config->mediaFolder, type);
+        mediaTypeFolder = PathTools::concatPath(config->mediaFolder, type);
     }
     return mediaTypeFolder;
 }
@@ -353,7 +357,7 @@ QString AttractMode::getMediaTypeFolder(QString type, bool detectVideoPath) {
     }
 
     if (type != "video" && mediaTypeFolder.isEmpty()) {
-        mediaTypeFolder = Config::concatPath(config->mediaFolder, type);
+        mediaTypeFolder = PathTools::concatPath(config->mediaFolder, type);
     }
 
     return mediaTypeFolder;

src/cache.cpp

@@ -29,6 +29,7 @@
 #include "cli.h"
 #include "config.h"
 #include "nametools.h"
+#include "pathtools.h"
 #include "queue.h"
 #include "skyscraper.h"
 
@@ -367,30 +368,22 @@ void Cache::printCacheEditMenu() {
            "\033[1;33mx\033[0m)\n");
 }
 
-void Cache::editResources(QSharedPointer<Queue> queue, const QString &command,
-                          const QString &type) {
+int Cache::editResources(QSharedPointer<Queue> queue, const QString &command,
+                         const QString &type) {
     // Check sanity of command and parameters, if any
-    if (!command.isEmpty()) {
-        if (command == "new") {
-            if (!txtTypes().contains(type)) {
-                QStringList sortedTypes = txtTypes();
-                sortedTypes.sort();
-                printf("\033[1;31mUnknown resource type '%s', please specify "
-                       "one of the following:\033[0m '%s'.\n",
-                       type.toStdString().c_str(),
-                       sortedTypes.join("', '").toStdString().c_str());
-                return;
-            }
-        } else {
-            printf("\033[1;31mUnknown command '%s', please specify one of the "
-                   "following: 'new'.\033[0m\n",
-                   command.toStdString().c_str());
-            return;
-        }
+    if (command == "new" && !txtTypes().contains(type)) {
+        QStringList sortedTypes = txtTypes();
+        sortedTypes.sort();
+        printf("\033[1;31mUnknown resource type '%s', please specify "
+               "one of the following:\033[0m '%s'.\n",
+               type.toStdString().c_str(),
+               sortedTypes.join("', '").toStdString().c_str());
+        return -1;
     }
 
+    int retVal = 0;
     int queueLength = queue->length();
-    printf("\033[1mEntering resource cache editing mode! This mode allows "
+    printf("\033[1mEntering resource cache editing mode.\n\nThis mode allows "
            "you to edit textual resources for your files. To add media "
            "resources use the 'import' scraping module instead.\nYou "
            "can provide one or more file names on command line to edit "
@@ -616,9 +609,9 @@ void Cache::editResources(QSharedPointer<Queue> queue, const QString &command,
                         }
                         resources.append(newRes);
                         if (updated) {
-                            printf("[*] Updated existing ");
+                            printf("[\033[1;34m*\033[0m] Updated existing ");
                         } else {
-                            printf("[+] Added ");
+                            printf("[\033[1;32m+\033[0m] Added ");
                         }
                         printf("resource with value '\033[1;32m%s\033[0m'\n\n",
                                value.toStdString().c_str());
@@ -713,7 +706,8 @@ void Cache::editResources(QSharedPointer<Queue> queue, const QString &command,
                         QString delType = resources[idxInResList].type;
                         QString delSource = resources[idxInResList].source;
                         resources.removeAt(idxInResList);
-                        printf("[-] Removed resource: %s (%s)\n\n",
+                        printf("[\033[1;31m-\033[0m] Removed resource: %s "
+                               "(%s)\n\n",
                                delType.toStdString().c_str(),
                                delSource.toStdString().c_str());
 
@@ -727,7 +721,8 @@ void Cache::editResources(QSharedPointer<Queue> queue, const QString &command,
                 while (it.hasNext()) {
                     Resource res = it.next();
                     if (res.cacheId == cacheId) {
-                        printf("[-] Removed \033[1;33m%s\033[0m (%s) with "
+                        printf("[\033[1;31m-\033[0m] Removed "
+                               "\033[1;33m%s\033[0m (%s) with "
                                "value '\033[1;32m%s\033[0m'\n",
                                res.type.toStdString().c_str(),
                                res.source.toStdString().c_str(),
@@ -784,7 +779,8 @@ void Cache::editResources(QSharedPointer<Queue> queue, const QString &command,
                             removed++;
                         }
                     }
-                    printf("[-] Removed %d %s connected to rom from "
+                    printf("[\033[1;31m-\033[0m] Removed %d %s connected to "
+                           "rom from "
                            "module '\033[1;32m%s\033[0m'\n\n",
                            removed,
                            pluralizeWordStd("resource", removed != 1).c_str(),
@@ -842,7 +838,8 @@ void Cache::editResources(QSharedPointer<Queue> queue, const QString &command,
                             removed++;
                         }
                     }
-                    printf("[-] Removed %d %s connected to rom of "
+                    printf("[\033[1;31m-\033[0m] Removed %d %s connected to "
+                           "rom of "
                            "type '\033[1;32m%s\033[0m'\n\n",
                            removed,
                            pluralizeWordStd("resource", removed != 1).c_str(),
@@ -853,8 +850,11 @@ void Cache::editResources(QSharedPointer<Queue> queue, const QString &command,
                            typeInput.c_str());
                 }
             } else if (userInput == "c" || userInput == "x") {
-                printf("[!] Exiting without saving changes.\n");
-                exit(0);
+                printf(
+                    "[\033[1;33m!\033[0m] Exiting without saving changes.\n");
+                queue->clear();
+                doneEdit = true;
+                retVal = 1;
             } else if (userInput == "q" || userInput == "w") {
                 queue->clear();
                 doneEdit = true;
@@ -865,6 +865,7 @@ void Cache::editResources(QSharedPointer<Queue> queue, const QString &command,
             }
         }
     }
+    return retVal;
 }
 
 bool Cache::purgeResources(QString purgeStr) {
@@ -1008,8 +1009,8 @@ bool Cache::reportAllPlatform(Settings &config, Skyscraper *app) {
     for (const auto &platform :
          cacheDir.entryList(QDir::Dirs | QDir::NoDotAndDotDot)) {
         config.platform = platform;
-        config.cacheFolder = Config::concatPath(initCacheFolder, platform);
-        config.inputFolder = Config::concatPath(initInputFolder, platform);
+        config.cacheFolder = PathTools::concatPath(initCacheFolder, platform);
+        config.inputFolder = PathTools::concatPath(initInputFolder, platform);
         qDebug() << "reportAllPlatform()" << config.inputFolder;
         Cache cache(config.cacheFolder);
         if (cache.read()) {
@@ -1043,8 +1044,8 @@ void Cache::vacuumAllPlatform(Settings &config, Skyscraper *app) {
     for (const auto &platform :
          cacheDir.entryList(QDir::Dirs | QDir::NoDotAndDotDot)) {
         config.platform = platform;
-        config.cacheFolder = Config::concatPath(initCacheFolder, platform);
-        config.inputFolder = Config::concatPath(initInputFolder, platform);
+        config.cacheFolder = PathTools::concatPath(initCacheFolder, platform);
+        config.inputFolder = PathTools::concatPath(initInputFolder, platform);
         qDebug() << "vacuumAllPlatform()" << config.inputFolder;
         Cache cache(config.cacheFolder);
         if (cache.read() &&
@@ -1065,8 +1066,8 @@ void Cache::validateAllPlatform(Settings &config, Skyscraper *app) {
     for (const auto &platform :
          cacheDir.entryList(QDir::Dirs | QDir::NoDotAndDotDot)) {
         config.platform = platform;
-        config.cacheFolder = Config::concatPath(initCacheFolder, platform);
-        config.inputFolder = Config::concatPath(initInputFolder, platform);
+        config.cacheFolder = PathTools::concatPath(initCacheFolder, platform);
+        config.inputFolder = PathTools::concatPath(initInputFolder, platform);
         qDebug() << "validateAllPlatform()" << config.inputFolder;
         Cache cache(cacheDir.filePath(platform));
         if (cache.read()) {
@@ -1240,11 +1241,11 @@ bool Cache::assembleReport(const Settings &config, const QString filter) {
             reportFile.close();
             printf("\033[1;32m Done!\033[0m\n\033[1;33m  %d of %d %s "
                    "miss the '%s' resource.\033[0m\n",
-                   missing, fileInfos.length(),
+                   missing, static_cast<int>(fileInfos.length()),
                    pluralizeWordStd("file", fileInfos.length() != 1).c_str(),
                    resType.toStdString().c_str());
             if (missing > 0) {
-                printf("  Files in: %s\n", Config::pathToCStr(rFn));
+                printf("  Files in: %s\n", PathTools::pathToCStr(rFn));
             }
             printf("\n");
         } else {
@@ -1698,12 +1699,6 @@ QList<Resource> Cache::getResources() { return resources; }
 
 void Cache::addResources(GameEntry &entry, const Settings &config,
                          QString &output) {
-    if (entry.source.isEmpty()) {
-        printf("Something is wrong, resource with cache id '%s' has no source, "
-               "exiting...\n",
-               entry.cacheId.toStdString().c_str());
-        exit(1);
-    }
     if (entry.cacheId.isEmpty()) {
         return;
     }