[ 1585270 ] Further fixes to wxPathList

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@42538 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/pathlist.tex

@@ -2,12 +2,10 @@
 
 The path list is a convenient way of storing a number of directories, and
 when presented with a filename without a directory, searching for an existing file
-in those directories.  Storing the filename only in an application's files and
+in those directories.
-using a locally-defined list of directories makes the application and its files more
-portable.
 
-Use the \helpref{wxFileName::SplitPath}{wxfilenamesplitpath} global function 
+Be sure to look also at \helpref{wxStandardPaths}{wxstandardpaths} if you only
-to extract the filename from the path.
+want to search files in some standard paths.
 
 \wxheading{Derived from}
 
@@ -40,17 +38,19 @@ Constructs the object calling the \helpref{Add}{wxpathlistadd} function.
 \func{void}{AddEnvList}{\param{const wxString\& }{env\_variable}}
 
 Finds the value of the given environment variable, and adds all paths
-to the path list. Useful for finding files in the PATH variable, for
+to the path list. Useful for finding files in the {\tt PATH} variable, for
 example.
 
 
 \membersection{wxPathList::Add}\label{wxpathlistadd}
 
-\func{void}{Add}{\param{const wxString\& }{path}}
+\func{bool}{Add}{\param{const wxString\& }{path}}
 
 \func{void}{Add}{\param{const wxArrayString\& }{arr}}
 
 The first form adds the given directory to the path list, if the path is not already in the list.
+If the path cannot be normalized for some reason, it returns \false.
+
 The second form just calls the first form on all elements of the given array.
 
 The {\it path} is always considered a directory but no existence checks will be done on it
@@ -63,34 +63,42 @@ The {\it path} is always considered a directory but no existence checks will be
 
 \membersection{wxPathList::EnsureFileAccessible}\label{wxpathlistensurefileaccessible}
 
-\func{void}{EnsureFileAccessible}{\param{const wxString\& }{filename}}
+\func{bool}{EnsureFileAccessible}{\param{const wxString\& }{filename}}
 
-Given a full filename (with path), ensures that files in the same path
+Given a full filename (with path), ensures that the file exists and
-can be accessed using the pathlist. It does this by stripping the
+then calls \helpref{Add}{wxpathlistadd} with the path of the file.
-filename and adding the path to the list if not already there.
+
+Returns \false if the file does not exist (and in this case its path won't be added).
 
 
 \membersection{wxPathList::FindAbsoluteValidPath}\label{wxpathlistfindabsolutepath}
 
 \constfunc{wxString}{FindAbsoluteValidPath}{\param{const wxString\& }{file}}
 
-Searches for a full (i.e. absolute) path for an existing file by appending {\it file} to
+Like \helpref{FindValidPath}{wxpathlistfindvalidpath} but this function always
-successive members of the path list.  If the file wasn't found, an empty
+returns an absolute path (eventually prepending the current working directory
-string is returned.
+to the value returned \helpref{FindValidPath}{wxpathlistfindvalidpath}) or an
+empty string.
 
 
 \membersection{wxPathList::FindValidPath}\label{wxpathlistfindvalidpath}
 
 \constfunc{wxString}{FindValidPath}{\param{const wxString\& }{file}}
 
-Searches for a path for an existing file by appending {\it file} to
+Searches the given file in all paths stored in this class.
-successive members of the path list.
+The first path which concatenated to the given string points to an existing
-If the file wasn't found, an empty string is returned.
+file (see \helpref{wxFileExists}{wxfileexists}) is returned.
 
-The returned path may be relative to the current working directory.
+If the file wasn't found in any of the stored paths, an empty string is returned.
 
 The given string must be a file name, eventually with a path prefix (if the path
 prefix is absolute, only its name will be searched); i.e. it must not end with
 a directory separator (see \helpref{wxFileName::GetPathSeparator}{wxfilenamegetpathseparator})
 otherwise an assertion will fail.
 
+The returned path may be relative to the current working directory.
+Note in fact that wxPathList can be used to store both relative and absolute paths so that
+if you \helpref{Add()}{wxpathlistadd}ed relative paths, then the current working directory
+(see \helpref{wxGetCwd}{wxgetcwd} and \helpref{wxSetWorkingDirectory}{wxsetworkingdirectory})
+may affect the value returned by this function!
+

include/wx/filefn.h

@@ -669,7 +669,7 @@ public:
     void AddEnvList(const wxString& envVariable);
 
     // Adds given path to this list
-    void Add(const wxString& path);
+    bool Add(const wxString& path);
     void Add(const wxArrayString &paths);
 
     // Find the first full path for which the file exists
@@ -680,10 +680,12 @@ public:
     wxString FindAbsoluteValidPath(const wxString& filename) const;
 
     // Given full path and filename, add path to list
-    void EnsureFileAccessible(const wxString& path);
+    bool EnsureFileAccessible(const wxString& path);
 
+#if WXWIN_COMPATIBILITY_2_6
     // Returns true if the path is in the list
     wxDEPRECATED( bool Member(const wxString& path) const );
+#endif
 };
 
 #endif // _WX_FILEFN_H_

src/common/filefn.cpp

@@ -156,7 +156,7 @@ WXDLLEXPORT int wxOpen( const wxChar *pathname, int flags, mode_t mode )
 // wxPathList
 // ----------------------------------------------------------------------------
 
-void wxPathList::Add(const wxString& path)
+bool wxPathList::Add(const wxString& path)
 {
     // add a path separator to force wxFileName to interpret it always as a directory
     // (i.e. if we are called with '/home/user' we want to consider it a folder and
@@ -164,11 +164,17 @@ void wxPathList::Add(const wxString& path)
     wxFileName fn(path + wxFileName::GetPathSeparator());
 
     // add only normalized relative/absolute paths
-    fn.Normalize(wxPATH_NORM_DOTS|wxPATH_NORM_TILDE|wxPATH_NORM_LONG|wxPATH_NORM_ENV_VARS);
+    // NB: we won't do wxPATH_NORM_DOTS in order to avoid problems when trying to
+    //     normalize paths which starts with ".." (which can be normalized only if
+    //     we use also wxPATH_NORM_ABSOLUTE - which we don't want to use).
+    if (!fn.Normalize(wxPATH_NORM_TILDE|wxPATH_NORM_LONG|wxPATH_NORM_ENV_VARS))
+        return false;
 
     wxString toadd = fn.GetPath();
     if (Index(toadd) == wxNOT_FOUND)
         wxArrayString::Add(toadd);      // do not add duplicates
+
+    return true;
 }
 
 void wxPathList::Add(const wxArrayString &arr)
@@ -207,21 +213,17 @@ void wxPathList::AddEnvList (const wxString& WXUNUSED_IN_WINCE(envVariable))
 // Given a full filename (with path), ensure that that file can
 // be accessed again USING FILENAME ONLY by adding the path
 // to the list if not already there.
-void wxPathList::EnsureFileAccessible (const wxString& path)
+bool wxPathList::EnsureFileAccessible (const wxString& path)
 {
-    wxString path_only(wxPathOnly(path));
+    return Add(wxPathOnly(path));
-    if ( !path_only.empty() )
-    {
-        if ( Index(path_only) == wxNOT_FOUND )
-            Add(path_only);
-    }
 }
 
-// deprecated !
+#if WXWIN_COMPATIBILITY_2_6
 bool wxPathList::Member (const wxString& path) const
 {
     return Index(path) != wxNOT_FOUND;
 }
+#endif
 
 wxString wxPathList::FindValidPath (const wxString& file) const
 {
@@ -230,8 +232,13 @@ wxString wxPathList::FindValidPath (const wxString& file) const
     wxFileName fn(file);
     wxString strend;
 
-    // NB: normalize without making absolute !
+    // NB: normalize without making absolute otherwise calling this function with
-    fn.Normalize(wxPATH_NORM_DOTS|wxPATH_NORM_TILDE|wxPATH_NORM_LONG|wxPATH_NORM_ENV_VARS);
+    //     e.g. "b/c.txt" would result in removing the directory 'b' and the for loop
+    //     below would only add to the paths of this list the 'c.txt' part when doing
+    //     the existence checks...
+    // NB: we don't use wxPATH_NORM_DOTS here, too (see wxPathList::Add for more info)
+    if (!fn.Normalize(wxPATH_NORM_TILDE|wxPATH_NORM_LONG|wxPATH_NORM_ENV_VARS))
+        return wxEmptyString;
 
     wxASSERT_MSG(!fn.IsDir(), wxT("Cannot search for directories; only for files"));
     if (fn.IsAbsolute())