From 2530e04720b9252299ec509dbe5ca03515c0c8ed Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Sun, 11 Jan 2009 14:47:51 +0000
Subject: [PATCH] add some-system-path<->string functions to scheme/path

svn: r13065
---
 collects/scheme/path.ss                    | 19 +++++++++++++-
 collects/scribblings/reference/paths.scrbl | 29 ++++++++++++++++++++--
 collects/tests/mzscheme/pathlib.ss         | 10 ++++++++
 3 files changed, 55 insertions(+), 3 deletions(-)

diff --git a/collects/scheme/path.ss b/collects/scheme/path.ss
index 26ec3e2180..f047a1ebf0 100644
--- a/collects/scheme/path.ss
+++ b/collects/scheme/path.ss
@@ -6,7 +6,9 @@
          normalize-path
          filename-extension
          file-name-from-path
-         path-only)
+         path-only
+         some-system-path->string
+         string->some-system-path)
 
 (define (simple-form-path p)
   (unless (path-string? p)
@@ -168,3 +170,18 @@
          [name (and name (path->bytes name))])
     (cond [(and name (regexp-match #rx#"[.]([^.]+)$" name)) => cadr]
           [else #f])))
+
+(define (some-system-path->string path)
+  (unless (path-for-some-system? path)
+    (raise-type-error 'some-system-path->string "path (for any platform)" path))
+  (bytes->string/utf-8 (path->bytes path)))
+
+(define (string->some-system-path path kind)
+  (unless (string? path)
+    (raise-type-error 'string->some-system-path "string" path))
+  (unless (or (eq? kind 'unix)
+              (eq? kind 'windows))
+    (raise-type-error 'string->some-system-path "'unix or 'windows" kind))
+  (bytes->path (string->bytes/utf-8 path) kind))
+
+
diff --git a/collects/scribblings/reference/paths.scrbl b/collects/scribblings/reference/paths.scrbl
index b221a2840b..068983d6f1 100644
--- a/collects/scribblings/reference/paths.scrbl
+++ b/collects/scribblings/reference/paths.scrbl
@@ -65,7 +65,9 @@ Beware that the current locale might not encode every string, in which
 case @scheme[string->path] can produce the same path for different
 @scheme[str]s. See also @scheme[string->path-element], which should be
 used instead of @scheme[string->path] when a string represents a
-single path element.}
+single path element.
+
+See also @scheme[string->some-system-path].}
 
 @defproc[(bytes->path [bstr bytes?]
                       [type (or/c 'unix 'windows) (system-path-convention-type)]) 
@@ -97,7 +99,9 @@ Furthermore, for display and sorting based on individual path elements
 (such as pathless file names), use @scheme[path-element->string],
 instead, to avoid special encodings use to represent some relative
 paths. See @secref["windowspaths"] for specific information about
-the conversion of Windows paths.}
+the conversion of Windows paths.
+
+See also @scheme[some-system-path->string].}
 
 @defproc[(path->bytes [path path?]) bytes?]{
 
@@ -560,6 +564,27 @@ Returns @scheme[(simplify-path (path->complete-path path))], which
 ensures that the result is a complete path containing no up- or
 same-directory indicators.}
 
+@defproc[(some-system-path->string [path path-for-some-system?])
+         string?]{
+
+Converts @scheme[path] to a string using a UTF-8 encoding of the
+path's bytes.
+
+Use this function when working with paths for a different system
+(whose encoding of pathnames might be unrelated to the current
+locale's encoding) and when starting and ending with strings.}
+
+@defproc[(string->some-system-path [str string?]
+                                   [kind (or/c 'unix 'windows)])
+         path-for-some-system?]{
+
+Converts @scheme[str] to a @scheme[kind] path using a UTF-8 encoding
+of the path's bytes.
+
+Use this function when working with paths for a different system
+(whose encoding of pathnames might be unrelated to the current
+locale's encoding) and when starting and ending with strings.}
+
 @;------------------------------------------------------------------------
 @include-section["unix-paths.scrbl"]
 @include-section["windows-paths.scrbl"]
diff --git a/collects/tests/mzscheme/pathlib.ss b/collects/tests/mzscheme/pathlib.ss
index 262d83a444..a1f53be883 100644
--- a/collects/tests/mzscheme/pathlib.ss
+++ b/collects/tests/mzscheme/pathlib.ss
@@ -66,4 +66,14 @@
 
 ;; ----------------------------------------
 
+(test "a" some-system-path->string (string->path "a"))
+(test "a" some-system-path->string (bytes->path #"a" 'unix))
+(test "a" some-system-path->string (bytes->path #"a" 'windows))
+(test #t path-for-some-system? (string->some-system-path "a" 'unix))
+(test #t path-for-some-system? (string->some-system-path "a" 'windows))
+(test "a" some-system-path->string (string->some-system-path "a" 'unix))
+(test "a" some-system-path->string (string->some-system-path "a" 'windows))
+
+;; ----------------------------------------
+
 (report-errs)