From 9885dadfff6bc8fe25ba7eb2cb45e4ddaeae1c33 Mon Sep 17 00:00:00 2001
From: "Zheng, Lei" <realthunder.dev@gmail.com>
Date: Fri, 6 Aug 2021 14:46:56 +0800
Subject: [PATCH] App: use enum in API Application::getDocumentByPath()

---
 src/App/Application.cpp |  8 ++++----
 src/App/Application.h   | 29 +++++++++++++++++++++++------
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/src/App/Application.cpp b/src/App/Application.cpp
index 97c3bce6b5..72db851cba 100644
--- a/src/App/Application.cpp
+++ b/src/App/Application.cpp
@@ -629,7 +629,7 @@ Document* Application::openDocument(const char * FileName, bool createView) {
     return 0;
 }
 
-Document *Application::getDocumentByPath(const char *path, int checkCanonical) const {
+Document *Application::getDocumentByPath(const char *path, PathMatchMode checkCanonical) const {
     if(!path || !path[0])
         return nullptr;
     if(DocFileMap.empty()) {
@@ -643,7 +643,7 @@ Document *Application::getDocumentByPath(const char *path, int checkCanonical) c
     if(it != DocFileMap.end())
         return it->second;
 
-    if (!checkCanonical)
+    if (checkCanonical == MatchAbsolute)
         return nullptr;
 
     std::string filepath = FileInfo(path).filePath();
@@ -651,7 +651,7 @@ Document *Application::getDocumentByPath(const char *path, int checkCanonical) c
     for (auto &v : DocMap) {
         QFileInfo fi(QString::fromUtf8(v.second->FileName.getValue()));
         if (canonicalPath == fi.canonicalFilePath()) {
-            if (checkCanonical == 1)
+            if (checkCanonical == MatchCanonical)
                 return v.second;
             bool samePath = (canonicalPath == QString::fromUtf8(filepath.c_str()));
             FC_WARN("Identical physical path '" << canonicalPath.toUtf8().constData() << "'\n"
@@ -883,7 +883,7 @@ Document* Application::openDocumentPrivate(const char * FileName,
     }
 
     // Before creating a new document we check whether the document is already open
-    auto doc = getDocumentByPath(File.filePath().c_str(), 2);
+    auto doc = getDocumentByPath(File.filePath().c_str(), MatchCanonicalWarning);
     if(doc) {
         if(doc->testStatus(App::Document::PartialDoc)
                 || doc->testStatus(App::Document::PartialRestore)) {
diff --git a/src/App/Application.h b/src/App/Application.h
index 5042df74db..738c0e19d7 100644
--- a/src/App/Application.h
+++ b/src/App/Application.h
@@ -120,16 +120,33 @@ public:
     App::Document* getActiveDocument(void) const;
     /// Retrieve a named document
     App::Document* getDocument(const char *Name) const;
+
+    /// Path matching mode for getDocumentByPath()
+    enum PathMatchMode {
+        /// Match by resolving to absolute file path
+        MatchAbsolute = 0,
+        /** Match by absolute path first. If not found then match by resolving
+         * to canonical file path where any intermediate '.' '..' and symlinks
+         * are resolved.
+         */
+        MatchCanonical = 1,
+        /** Same as MatchCanonical, but if a document is found by canonical
+         * path match, which means the document can be resolved using two
+         * different absolute path, a warning is printed and the found document
+         * is not returned. This is to allow the caller to intentionally load
+         * the same physical file as separate documents.
+         */
+        MatchCanonicalWarning = 2,
+    };
     /** Retrieve a document based on file path
      *
      * @param path: file path
-     * @param checkCanonical: if zero, only match absolute file path. If 1,
-     * then match by canonical file path, where any intermediate '.' and '..'
-     * and symlinks are resolved. If 2, then only print warning message if
-     * there is identical canonical file path found, but will not return the
-     * matched document.
+     * @param checkCanonical: file path matching mode, @sa PathMatchMode.
+     * @return Return the document found by matching with the given path
      */
-    App::Document* getDocumentByPath(const char *path, int checkCanonical=0) const;
+    App::Document* getDocumentByPath(const char *path,
+                                     PathMatchMode checkCanonical = MatchAbsolute) const;
+
     /// gets the (internal) name of the document
     const char * getDocumentName(const App::Document* ) const;
     /// get a list of all documents in the application