- USING: help.markup help.syntax io.backend io.files io.directories strings ;
-USING: help.markup help.syntax io.backend io.files strings
++USING: help.markup help.syntax io.backend io.files io.directories strings
+ sequences ;
IN: io.pathnames
HELP: path-separator?
HELP: normalize-path
{ $values { "str" "a pathname string" } { "newstr" "a new pathname string" } }
-{ $description "Called by words such as " { $link <file-reader> } " and " { $link <file-writer> } " to prepare a pathname before passing it to underlying code." } ;
+{ $description "Prepends the " { $link current-directory } " to the pathname, resolves a " { $snippet "resource:" } " prefix, if present, and performs any platform-specific pathname normalization." }
+{ $notes "High-level words, such as " { $link <file-reader> } " and " { $link delete-file } " call this word for you. It only needs to be called directly when passing pathnames to C functions or external processes. This is because Factor does not use the operating system's notion of a current directory, and instead maintains its own dynamically-scoped " { $link current-directory } " variable." }
+{ $examples
+ "For example, if you create a file named " { $snippet "data.txt" } " in the current directory, and wish to pass it to a process, you must normalize it:"
+ { $code
+ "\"1 2 3\" \"data.txt\" ascii set-file-contents"
+ "\"munge\" \"data.txt\" normalize-path 2array run-process"
+ }
+} ;
+ HELP: canonicalize-path
+ { $values { "path" "a pathname string" } { "path'" "a new pathname string" } }
+ { $description "Returns an canonical name for a path. The canonical name is an absolute path containing no symlinks." } ;
+
HELP: <pathname>
{ $values { "string" "a pathname string" } { "pathname" pathname } }
{ $description "Creates a new " { $link pathname } "." } ;
{ $subsection parent-directory }
{ $subsection file-name }
{ $subsection last-path-separator }
+ { $subsection path-components }
+ { $subsection prepend-path }
{ $subsection append-path }
++{ $subsection canonicalize-path }
"Pathname presentations:"
{ $subsection pathname }
-{ $subsection <pathname> } ;
+{ $subsection <pathname> }
+"Literal pathnames:"
+{ $subsection POSTPONE: P" }
+"Low-level word:"
+{ $subsection normalize-path } ;
ABOUT: "io.pathnames"