rewrite wxContractPath as wxFileName::ReplaceEnvVariable and wxFileName::ReplaceHomeDir; add test units and docs for them

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

include/wx/filename.h

@@ -353,6 +353,25 @@ public:
                            wxString* arguments = NULL);
 #endif
 
+#ifndef __WXWINCE__
+        // if the path contains the value of the environment variable named envname
+        // then this function replaces it with the string obtained from
+        //    wxString::Format(replacementFmtString, value_of_envname_variable)
+        //
+        // Example:
+        //    wxFileName fn("/usr/openwin/lib/someFile");
+        //    fn.ReplaceEnvVariable("OPENWINHOME");
+        //         // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile"
+    bool ReplaceEnvVariable(const wxString& envname,
+                            const wxString& replacementFmtString = "$%s",
+                            wxPathFormat format = wxPATH_NATIVE);
+#endif
+
+        // replaces, if present in the path, the home directory for the given user
+        // (see wxGetHomeDir) with a tilde
+    bool ReplaceHomeDir(wxPathFormat format = wxPATH_NATIVE);
+
+
     // Comparison
 
         // compares with the rules of the given platforms format

interface/wx/filename.h

@@ -36,7 +36,12 @@ enum wxPathFormat
 */
 enum wxPathNormalize
 {
-    wxPATH_NORM_ENV_VARS = 0x0001,  //!< Replace environment variables with their values.
+    //! Replace environment variables with their values.
+    //! wxFileName understands both Unix and Windows (but only under Windows) environment
+    //! variables expansion: i.e. @c "$var", @c "$(var)" and @c "${var}" are always understood
+    //! and in addition under Windows @c "%var%" is also.
+    wxPATH_NORM_ENV_VARS = 0x0001,
+
     wxPATH_NORM_DOTS     = 0x0002,  //!< Squeeze all @c ".." and @c "." and prepend the current working directory.
     wxPATH_NORM_TILDE    = 0x0004,  //!< Replace @c "~" and @c "~user" (Unix only).
     wxPATH_NORM_CASE     = 0x0008,  //!< If the platform is case insensitive, make lowercase the path.
@@ -924,6 +929,53 @@ public:
     */
     void RemoveLastDir();
 
+    /**
+        If the path contains the value of the environment variable named @a envname
+        then this function replaces it with the string obtained from
+        wxString::Format(replacementFmtString, value_of_envname_variable).
+
+        This function is useful to make the path shorter or to make it dependent
+        from a certain environment variable.
+        Normalize() with @c wxPATH_NORM_ENV_VARS can perform the opposite of this
+        function (depending on the value of @a replacementFmtString).
+
+        The name and extension of this filename are not modified.
+
+        Example:
+        @code
+            wxFileName fn("/usr/openwin/lib/someFile");
+            fn.ReplaceEnvVariable("OPENWINHOME");
+                    // now fn.GetFullPath() == "$OPENWINHOME/lib/someFile"
+        @endcode
+
+        @since 2.9.0
+
+        @return @true if the operation was successful (which doesn't mean
+                that something was actually replaced, just that ::wxGetEnv
+                didn't fail).
+    */
+    bool ReplaceEnvVariable(const wxString& envname,
+                            const wxString& replacementFmtString = "$%s",
+                            wxPathFormat format = wxPATH_NATIVE);
+
+    /**
+        Replaces, if present in the path, the home directory for the given user
+        (see ::wxGetHomeDir) with a tilde (~).
+
+        Normalize() with @c wxPATH_NORM_TILDE performs the opposite of this
+        function.
+
+        The name and extension of this filename are not modified.
+
+        @since 2.9.0
+
+        @return @true if the operation was successful (which doesn't mean
+                that something was actually replaced, just that ::wxGetHomeDir
+                didn't fail).
+    */
+    bool ReplaceHomeDir(wxPathFormat format = wxPATH_NATIVE);
+
+
     /**
         Deletes the specified directory from the file system.
     */

src/common/filename.cpp

@@ -1152,7 +1152,6 @@ bool wxFileName::Normalize(int flags,
         }
     }
 
-
     // the existing path components
     wxArrayString dirs = GetDirs();
 
@@ -1302,6 +1301,49 @@ bool wxFileName::Normalize(int flags,
     return true;
 }
 
+#ifndef __WXWINCE__
+bool wxFileName::ReplaceEnvVariable(const wxString& envname,
+                                    const wxString& replacementFmtString,
+                                    wxPathFormat format)
+{
+    // look into stringForm for the contents of the given environment variable
+    wxString val;
+    if (envname.empty() ||
+        !wxGetEnv(envname, &val))
+        return false;
+    if (val.empty())
+        return false;
+
+    wxString stringForm = GetPath(wxPATH_GET_VOLUME, format);
+        // do not touch the file name and the extension
+
+    wxString replacement = wxString::Format(replacementFmtString, envname);
+    stringForm.Replace(val, replacement);
+
+    // Now assign ourselves the modified path:
+    Assign(stringForm, GetFullName(), format);
+
+    return true;
+}
+#endif
+
+bool wxFileName::ReplaceHomeDir(wxPathFormat format)
+{
+    wxString homedir = wxGetHomeDir();
+    if (homedir.empty())
+        return false;
+
+    wxString stringForm = GetPath(wxPATH_GET_VOLUME, format);
+        // do not touch the file name and the extension
+
+    stringForm.Replace(homedir, "~");
+
+    // Now assign ourselves the modified path:
+    Assign(stringForm, GetFullName(), format);
+
+    return true;
+}
+
 // ----------------------------------------------------------------------------
 // get the shortcut target
 // ----------------------------------------------------------------------------

tests/filename/filenametest.cpp

@@ -120,8 +120,11 @@ private:
         CPPUNIT_TEST( TestComparison );
         CPPUNIT_TEST( TestSplit );
         CPPUNIT_TEST( TestSetPath );
+#if WXWIN_COMPATIBILITY_2_8
         CPPUNIT_TEST( TestStrip );
+#endif
         CPPUNIT_TEST( TestNormalize );
+        CPPUNIT_TEST( TestReplace );
 #ifdef __WINDOWS__
         CPPUNIT_TEST( TestShortLongPath );
 #endif // __WINDOWS__
@@ -131,8 +134,11 @@ private:
     void TestComparison();
     void TestSplit();
     void TestSetPath();
+#if WXWIN_COMPATIBILITY_2_8
     void TestStrip();
+#endif
     void TestNormalize();
+    void TestReplace();
 #ifdef __WINDOWS__
     void TestShortLongPath();
 #endif // __WINDOWS__
@@ -375,6 +381,80 @@ void FileNameTestCase::TestNormalize()
     }
 }
 
+void FileNameTestCase::TestReplace()
+{
+    static const struct FileNameTest
+    {
+        const char *original;
+        const char *env_contents;
+        const char *replace_fmtstring;
+        const char *expected;
+        wxPathFormat fmt;
+    } tests[] =
+    {
+        { "/usr/a/strange path/lib/someFile.ext", "/usr/a/strange path", "$%s", "$TEST_VAR/lib/someFile.ext", wxPATH_UNIX },
+        { "/usr/a/path/lib/someFile.ext", "/usr/a/path", "$%s", "$TEST_VAR/lib/someFile.ext", wxPATH_UNIX },
+        { "/usr/a/path/lib/someFile", "/usr/a/path/", "$%s", "$TEST_VARlib/someFile", wxPATH_UNIX },
+        { "/usr/a/path/lib/", "/usr/a/path/", "$(%s)", "$(TEST_VAR)lib/", wxPATH_UNIX },
+        { "/usr/a/path/lib/", "/usr/a/path/", "${{%s}}", "${{TEST_VAR}}lib/", wxPATH_UNIX },
+        { "/usr/a/path/lib/", "/usr/a/path/", "%s", "TEST_VARlib/", wxPATH_UNIX },
+        { "/usr/a/path/lib/", "/usr/a/path/", "%s//", "TEST_VAR/lib/", wxPATH_UNIX },
+            // note: empty directory components are automatically removed by wxFileName thus
+            //       using // in the replace format string has no effect
+
+        { "/usr/../a/path/lib/", "/usr/a/path/", "%s", "/usr/../a/path/lib/", wxPATH_UNIX },
+        { "/usr/a/path/usr/usr", "/usr", "%s", "TEST_VAR/a/pathTEST_VAR/usr", wxPATH_UNIX },
+        { "/usr/a/path/usr/usr", "/usr", "$%s", "$TEST_VAR/a/path$TEST_VAR/usr", wxPATH_UNIX },
+        { "/a/b/c/d", "a/", "%s", "/TEST_VARb/c/d", wxPATH_UNIX },
+
+        { "C:\\A\\Strange Path\\lib\\someFile", "C:\\A\\Strange Path", "%%%s%%", "%TEST_VAR%\\lib\\someFile", wxPATH_WIN },
+        { "C:\\A\\Path\\lib\\someFile", "C:\\A\\Path", "%%%s%%", "%TEST_VAR%\\lib\\someFile", wxPATH_WIN },
+        { "C:\\A\\Path\\lib\\someFile", "C:\\A\\Path", "$(%s)", "$(TEST_VAR)\\lib\\someFile", wxPATH_WIN }
+    };
+
+    for ( size_t i = 0; i < WXSIZEOF(tests); i++ )
+    {
+        const FileNameTest& fnt = tests[i];
+        wxFileName fn(fnt.original, fnt.fmt);
+
+        // set the environment variable
+        wxSetEnv(_T("TEST_VAR"), fnt.env_contents);
+
+        // be sure this ReplaceEnvVariable does not fail
+        WX_ASSERT_MESSAGE
+        (
+            ("#%d: ReplaceEnvVariable(%s) failed", (int)i, fnt.replace_fmtstring),
+            fn.ReplaceEnvVariable("TEST_VAR", fnt.replace_fmtstring, fnt.fmt)
+        );
+
+        // compare result with expected string
+        wxString expected(fnt.expected);
+        WX_ASSERT_EQUAL_MESSAGE
+        (
+            ("array element #%d", (int)i),
+            expected, fn.GetFullPath(fnt.fmt)
+        );
+    }
+
+    // now test ReplaceHomeDir
+
+    wxFileName fn = wxFileName::DirName(wxGetHomeDir());
+    fn.AppendDir("test1");
+    fn.AppendDir("test2");
+    fn.AppendDir("test3");
+    fn.SetName("some file");
+
+    WX_ASSERT_MESSAGE
+    (
+        ("ReplaceHomeDir(%s) failed", fn.GetFullPath()),
+        fn.ReplaceHomeDir()
+    );
+
+    CPPUNIT_ASSERT_EQUAL( wxString(_T("~/test1/test2/test3/some file")),
+                          fn.GetFullPath(wxPATH_UNIX) );
+}
+
+#if WXWIN_COMPATIBILITY_2_8
 wxString wxTestStripExtension(wxString szFile)
 {
     wxStripExtension(szFile);
@@ -392,6 +472,7 @@ void FileNameTestCase::TestStrip()
     CPPUNIT_ASSERT_EQUAL( wxString(_T("good")), wxTestStripExtension(_T("good.wav")) );
     CPPUNIT_ASSERT_EQUAL( wxString(_T("good.wav")), wxTestStripExtension(_T("good.wav.wav")) );
 }
+#endif
 
 #ifdef __WINDOWS__