Added Canonical method

Author: cmaglie

paths.go

@@ -564,3 +564,18 @@ func (p *Path) Parents() []*Path {
 func (p *Path) String() string {
 	return p.path
 }
+
+// Canonical return a "canonical" Path for the given filename.
+// The meaning of "canonical" is OS-dependent but the goal of this method
+// is to always return the same path for a given file (factoring out all the
+// possibile ambiguities including, for example, relative paths traversal,
+// symlinks, drive volume letter case, etc).
+func (p *Path) Canonical() *Path {
+	canonical := p.Clone()
+	// https://github.com/golang/go/issues/17084#issuecomment-246645354
+	canonical.FollowSymLink()
+	if absPath, err := canonical.Abs(); err == nil {
+		canonical = absPath
+	}
+	return canonical
+}

paths_test.go

@@ -321,6 +321,25 @@ func TestEquivalentPaths(t *testing.T) {
 	}
 }
 
+func TestCanonicalize(t *testing.T) {
+	wd, err := Getwd()
+	require.NoError(t, err)
+
+	p := New("_testdata", "anotherFile").Canonical()
+	require.Equal(t, wd.Join("_testdata", "anotherFile").String(), p.String())
+
+	p = New("_testdata", "nonexistentFile").Canonical()
+	require.Equal(t, wd.Join("_testdata", "nonexistentFile").String(), p.String())
+
+	if runtime.GOOS == "windows" {
+		q := New("_testdata", "ANOTHE~1").Canonical()
+		require.Equal(t, wd.Join("_testdata", "anotherFile").String(), q.String())
+
+		r := New("c:\\").Canonical()
+		require.Equal(t, "C:\\", r.String())
+	}
+}
+
 func TestRelativeTo(t *testing.T) {
 	res, err := New("/my/abs/path/123/456").RelTo(New("/my/abs/path"))
 	require.NoError(t, err)