core/io/pathnames/pathnames-docs.factor

   1 USING: help.markup help.syntax io.backend io.files strings ;
   2 IN: io.pathnames
   3
   4 HELP: path-separator?
   5 { $values { "ch" "a code point" } { "?" "a boolean" } }
   6 { $description "Tests if the code point is a platform-specific path separator." }
   7 { $examples
   8     "On Unix:"
   9     { $example "USING: io.pathnames prettyprint ;" "CHAR: / path-separator? ." "t" }
  10 } ;
  11
  12 HELP: parent-directory
  13 { $values { "path" "a pathname string" } { "parent" "a pathname string" } }
  14 { $description "Strips the last component off a pathname." }
  15 { $examples { $example "USING: io io.pathnames ;" "\"/etc/passwd\" parent-directory print" "/etc/" } } ;
  16
  17 HELP: file-name
  18 { $values { "path" "a pathname string" } { "string" string } }
  19 { $description "Outputs the last component of a pathname string." }
  20 { $examples
  21     { $example "USING: io.pathnames prettyprint ;" "\"/usr/bin/gcc\" file-name ." "\"gcc\"" }
  22     { $example "USING: io.pathnames prettyprint ;" "\"/usr/libexec/awk/\" file-name ." "\"awk\"" }
  23 } ;
  24
  25 HELP: append-path
  26 { $values { "str1" "a string" } { "str2" "a string" } { "str" "a string" } }
  27 { $description "Appends " { $snippet "str1" } " and " { $snippet "str2" } " to form a pathname." } ;
  28
  29 HELP: prepend-path
  30 { $values { "str1" "a string" } { "str2" "a string" } { "str" "a string" } }
  31 { $description "Appends " { $snippet "str2" } " and " { $snippet "str1" } " to form a pathname." } ;
  32
  33 { append-path prepend-path } related-words
  34
  35 HELP: absolute-path?
  36 { $values { "path" "a pathname string" } { "?" "a boolean" } }
  37 { $description "Tests if a pathname is absolute. Examples of absolute pathnames are " { $snippet "/foo/bar" } " on Unix and " { $snippet "c:\\foo\\bar" } " on Windows." } ;
  38
  39 HELP: windows-absolute-path?
  40 { $values { "path" "a pathname string" } { "?" "a boolean" } }
  41 { $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." } ;
  42
  43 HELP: root-directory?
  44 { $values { "path" "a pathname string" } { "?" "a boolean" } }
  45 { $description "Tests if a pathname is a root directory. Examples of root directory pathnames are " { $snippet "/" } " on Unix and " { $snippet "c:\\" } " on Windows." } ;
  46
  47 { absolute-path? windows-absolute-path? root-directory? } related-words
  48
  49 HELP: resource-path
  50 { $values { "path" "a pathname string" } { "newpath" "a pathname string" } }
  51 { $description "Resolve a path relative to the Factor source code location." } ;
  52
  53 HELP: pathname
  54 { $class-description "Class of path name objects. Path name objects can be created by calling " { $link <pathname> } "." } ;
  55
  56 HELP: normalize-path
  57 { $values { "str" "a pathname string" } { "newstr" "a new pathname string" } }
  58 { $description "Called by words such as " { $link <file-reader> } " and " { $link <file-writer> } " to prepare a pathname before passing it to underlying code." } ;
  59
  60 HELP: <pathname>
  61 { $values { "string" "a pathname string" } { "pathname" pathname } }
  62 { $description "Creates a new " { $link pathname } "." } ;
  63
  64 HELP: home
  65 { $values { "dir" string } }
  66 { $description "Outputs the user's home directory." } ;
  67
  68 ARTICLE: "pathname-normalization" "Pathname normalization"
  69 "Words that take a pathname should normalize the pathname by calling " { $link normalize-path } ".When normalizing a pathname, the input pathname is either absolute or relative to the " { $link current-directory } ". If absolute, such as the root directories " { $snippet "/" } " or " { $snippet "c:\\" } ", the pathname is left alone, while if relative, the current directory is prepended to the pathname. If a pathname begins with the magic string " { $snippet "resource:" } ", this string is replaced with the Factor directory. On Windows, all pathnames, absolute and relative, are converted to Unicode pathamess." ;
  70
  71 ARTICLE: "io.pathnames" "Pathname manipulation"
  72 { $subsection "pathname-normalization" }
  73 "Literal pathnames:"
  74 { $subsection POSTPONE: P" }
  75 "Pathname manipulation:"
  76 { $subsection normalize-path }
  77 { $subsection parent-directory }
  78 { $subsection file-name }
  79 { $subsection last-path-separator }
  80 { $subsection append-path }
  81 "Pathname presentations:"
  82 { $subsection pathname }
  83 { $subsection <pathname> } ;
  84
  85 ABOUT: "io.pathnames"