core/io/pathnames/pathnames-docs.factor

   1 USING: help.markup help.syntax io.backend io.directories
   2 io.files io.pathnames.private kernel sequences strings system ;
   3 IN: io.pathnames
   4
   5 HELP: path-separator?
   6 { $values { "ch" "a code point" } { "?" boolean } }
   7 { $description "Tests if the code point is a platform-specific path separator." }
   8 { $examples
   9     "On Unix:"
  10     { $example "USING: io.pathnames prettyprint ;" "CHAR: / path-separator? ." "t" }
  11 } ;
  12
  13 HELP: parent-directory
  14 { $values { "path" "a pathname string" } { "parent" "a pathname string" } }
  15 { $description "Strips the last component off a pathname." }
  16 { $examples { $example "USING: io io.pathnames ;" "\"/etc/passwd\" parent-directory print" "/etc/" } } ;
  17
  18 HELP: file-name
  19 { $values { "path" "a pathname string" } { "string" string } }
  20 { $description "Outputs the last component of a pathname string." }
  21 { $examples
  22     { $example "USING: io.pathnames prettyprint ;" "\"/usr/bin/gcc\" file-name ." "\"gcc\"" }
  23     { $example "USING: io.pathnames prettyprint ;" "\"/usr/libexec/awk/\" file-name ." "\"awk\"" }
  24 } ;
  25
  26 HELP: file-extension
  27 { $values { "path" "a pathname string" } { "extension" string } }
  28 { $description "Outputs the extension of " { $snippet "path" } ", or " { $link f } " if the filename has no extension." }
  29 { $examples
  30     { $example "USING: io.pathnames prettyprint ;" "\"/usr/bin/gcc\" file-extension ." "f" }
  31     { $example "USING: io.pathnames prettyprint ;" "\"/home/csi/gui.vbs\" file-extension ." "\"vbs\"" }
  32 } ;
  33
  34 HELP: file-stem
  35 { $values { "path" "a pathname string" } { "stem" string } }
  36 { $description "Outputs the " { $link file-name } " of " { $snippet "path" } " with the file extension removed, if any." }
  37 { $examples
  38     { $example "USING: io.pathnames prettyprint ;" "\"/usr/bin/gcc\" file-stem ." "\"gcc\"" }
  39     { $example "USING: io.pathnames prettyprint ;" "\"/home/csi/gui.vbs\" file-stem ." "\"gui\"" }
  40 } ;
  41
  42 { file-name file-stem file-extension } related-words
  43
  44 HELP: path-components
  45 { $values { "path" "a pathnames string" } { "seq" sequence } }
  46 { $description "Splits a pathname on the " { $link path-separator } " into its its component strings." } ;
  47
  48 HELP: append-path
  49 { $values { "path1" "a pathname string" } { "path2" "a pathname string" } { "path" "a pathname string" } }
  50 { $description "Appends " { $snippet "path1" } " and " { $snippet "path2" } " to form a pathname." }
  51 { $examples
  52     { $unchecked-example "USING: io.pathnames prettyprint ;
  53 \"first\" \"second.txt\" append-path ."
  54 "\"first/second.txt\""
  55     }
  56 } ;
  57
  58 HELP: prepend-path
  59 { $values { "path1" "a pathname string" } { "path2" "a pathname string" } { "path" "a pathname string" } }
  60 { $description "Appends " { $snippet "path2" } " and " { $snippet "path1" } " to form a pathname." }
  61 { $examples
  62     { $unchecked-example "USING: io.pathnames prettyprint ;
  63 \"second.txt\" \"first\" prepend-path ."
  64 "\"first/second.txt\""
  65     }
  66 } ;
  67
  68 { append-path prepend-path } related-words
  69
  70 HELP: absolute-path?
  71 { $values { "path" "a pathname string" } { "?" boolean } }
  72 { $description "Tests if a pathname is absolute. Examples of absolute pathnames are " { $snippet "/foo/bar" } " on Unix and " { $snippet "c:\\foo\\bar" } " on Windows." } ;
  73
  74 HELP: windows-absolute-path?
  75 { $values { "path" "a pathname string" } { "?" boolean } }
  76 { $description "Tests if a pathname is absolute on Windows. Examples of absolute pathnames on Windows are " { $snippet "c:\\foo\\bar" } " and " { $snippet "\\\\?\\c:\\foo\\bar" } " for absolute Unicode pathnames." } ;
  77
  78 HELP: root-directory?
  79 { $values { "path" "a pathname string" } { "?" boolean } }
  80 { $description "Tests if a pathname is a root directory. Examples of root directory pathnames are " { $snippet "/" } " on Unix and " { $snippet "c:\\" } " on Windows." } ;
  81
  82 { absolute-path? windows-absolute-path? root-directory? } related-words
  83
  84 HELP: resource-path
  85 { $values { "path" "a pathname string" } { "newpath" "a pathname string" } }
  86 { $description "Resolve a path relative to the Factor source code location." } ;
  87
  88 HELP: pathname
  89 { $class-description "Class of path name objects. Path name objects can be created by calling " { $link <pathname> } "." } ;
  90
  91 HELP: normalize-path
  92 { $values { "path" "a pathname string" } { "path'" "a new pathname string" } }
  93 { $description "Prepends the " { $link current-directory } " to the pathname, resolves a " { $snippet "resource:" } " or " { $snippet "vocab:" } " prefix, if present (see " { $link "io.pathnames.special" } "). Also converts the path into a UNC path on Windows." }
  94 { $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." }
  95 { $notes "On Windows NT platforms, this word prepends the Unicode path prefix." }
  96 { $examples
  97   "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:"
  98   { $code
  99     "\"1 2 3\" \"data.txt\" ascii set-file-contents"
 100     "\"munge\" \"data.txt\" normalize-path 2array run-process"
 101   }
 102 } ;
 103
 104 HELP: absolute-path
 105 { $values
 106     { "path" "a pathname string" }
 107     { "path'" "a pathname string" }
 108 }
 109 { $description "Prepends the " { $link current-directory } " to the pathname and resolves a " { $snippet "resource:" } ", " { $snippet "~" } " or " { $snippet "vocab:" } " prefix, if present (see " { $link "io.pathnames.special" } ")." }
 110 { $notes "This word is exactly the same as " { $link normalize-path } ", except on Windows NT platforms, where it does not prepend the Unicode path prefix. Most code should call " { $link normalize-path } " instead." } ;
 111
 112 HELP: resolve-symlinks
 113 { $values { "path" "a pathname string" } { "path'" "a new pathname string" } }
 114 { $description "Outputs a path where none of the path components are symlinks. This word is useful for determining the actual path on disk where a file is stored; the root of this absolute path is a mount point in the file-system." }
 115 { $notes "Most code should not need to call this word except in very special circumstances. One use case is finding the actual file-system on which a file is stored." } ;
 116
 117 HELP: <pathname>
 118 { $values { "string" "a pathname string" } { "pathname" pathname } }
 119 { $description "Creates a new " { $link pathname } "." } ;
 120
 121 HELP: home
 122 { $values { "dir" string } }
 123 { $description "Outputs the user's home directory." }
 124 { $examples
 125     { $unchecked-example "USING: io.pathnames prettyprint ;"
 126                 "home ."
 127                 "\"/home/factor-user\""
 128     }
 129 } ;
 130
 131 ARTICLE: "io.pathnames.special" "Special pathnames"
 132 "If a pathname begins with " { $snippet "resource:" } ", it is resolved relative to the directory containing the current image (see " { $link image-path } ")."
 133 $nl
 134 "If a pathname begins with " { $snippet "vocab:" } ", then it will be searched for in all current vocabulary roots (see " { $link "add-vocab-roots" } ")."
 135 $nl
 136 "If a pathname begins with " { $snippet "~" } ", it will be searched for in the home directory. Subsequent tildes in the pathname will be construed as literal tilde path or filenames and will not be treated specially. To access a filename named " { $snippet "~" } ", you must construct a path to reference the filename, even if it's within the current directory such as " { $snippet "./~" } "." ;
 137
 138 ARTICLE: "io.pathnames.presentations" "Pathname presentations"
 139 "Pathname presentations are objects that wrap a pathname string. Clicking a pathname presentation in the UI brings up the file in one of the supported editors. See " { $link "editor" } " for more details."
 140 { $subsections
 141     pathname
 142     <pathname>
 143 }
 144 "Literal pathname presentations:"
 145 { $subsections POSTPONE: P" }
 146 "Many words that accept pathname strings can also work on pathname presentations." ;
 147
 148 ARTICLE: "io.pathnames" "Pathnames"
 149 "Pathnames are strings that refer to a file on disk. Pathname semantics are platform-specific, and Factor makes no attempt to abstract away the differences. Note that on Windows, both forward and backward slashes are accepted as directory separators."
 150 $nl
 151 "Pathname introspection:"
 152 { $subsections
 153     parent-directory
 154     file-name
 155     file-stem
 156     file-extension
 157     path-components
 158 }
 159 "Appending pathnames:"
 160 { $subsections
 161     prepend-path
 162     append-path
 163 }
 164 "Normalizing pathnames:"
 165 { $subsections normalize-path absolute-path resolve-symlinks }
 166 "Additional topics:"
 167 { $subsections "io.pathnames.presentations" "io.pathnames.special" } ;
 168
 169 ABOUT: "io.pathnames"