basis/io/files/info/info-docs.factor

   1 USING: arrays help.markup help.syntax kernel io.files ;
   2 IN: io.files.info
   3
   4 HELP: file-info
   5 { $values { "path" "a pathname string" } { "info" file-info-tuple } }
   6 { $description "Queries the file system for metadata. If " { $snippet "path" } " refers to a symbolic link, it is followed. See the article " { $link "file-types" } " for a list of metadata symbols." }
   7 { $errors "Throws an error if the file does not exist." } ;
   8
   9 HELP: link-info
  10 { $values { "path" "a pathname string" } { "info" file-info-tuple } }
  11 { $description "Queries the file system for metadata. If " { $snippet "path" } " refers to a symbolic link, information about the symbolic link itself is returned. See the article " { $link "file-types" } " for a list of metadata symbols." }
  12 { $errors "Throws an error if the file does not exist." } ;
  13
  14 { file-info link-info file-info-tuple } related-words
  15
  16 HELP: directory?
  17 { $values { "path/info" { $or "a pathname string" file-info-tuple } } { "?" boolean } }
  18 { $description "Tests if " { $snippet "path/info" } " is a directory." } ;
  19
  20 HELP: regular-file?
  21 { $values { "path/info" { $or "a pathname string" file-info-tuple } } { "?" boolean } }
  22 { $description "Tests if " { $snippet "path/info" } " is a normal file." } ;
  23
  24 HELP: symbolic-link?
  25 { $values { "path/info" { $or "a pathname string" file-info-tuple } } { "?" boolean } }
  26 { $description "Tests if " { $snippet "path/info" } " is a symbolic link." } ;
  27
  28 HELP: file-systems
  29 { $values { "array" array } }
  30 { $description "Returns an array of " { $link file-system-info } " objects returned by iterating the mount points and calling " { $link file-system-info } " on each." }
  31 { $notes "File systems that the process doesn't have access to aren't included." } ;
  32
  33 HELP: file-system-info
  34 { $values
  35 { "path" "a pathname string" }
  36 { "file-system-info" file-system-info-tuple } }
  37 { $description "Returns a platform-specific object describing the file-system that contains the path. The cross-platform slot is " { $slot "free-space" } "." }
  38 { $examples
  39     { $unchecked-example
  40         "USING: io.files.info io.pathnames math prettyprint ;"
  41         "IN: scratchpad"
  42         ""
  43         ": gb ( m -- n ) 30 2^ * ;"
  44         ""
  45         "home file-system-info free-space>> 100 gb < ."
  46         "f"
  47     }
  48 } ;
  49
  50 HELP: file-readable?
  51 { $values { "path" "a pathname string" } { "?" boolean } }
  52 { $description "Returns whether the file specified by " { $snippet "path" } " is readable by the current process." }
  53 { $errors "Throws an error if the file does not exist." } ;
  54
  55 HELP: file-writable?
  56 { $values { "path" "a pathname string" } { "?" boolean } }
  57 { $description "Returns whether the file specified by " { $snippet "path" } " is writable by the current process." }
  58 { $errors "Throws an error if the file does not exist." } ;
  59
  60 HELP: file-executable?
  61 { $values { "path" "a pathname string" } { "?" boolean } }
  62 { $description "Returns whether the file specified by " { $snippet "path" } " is executable by the current process." }
  63 { $errors "Throws an error if the file does not exist." } ;
  64
  65 ARTICLE: "io.files.info" "File system metadata"
  66 "File metadata:"
  67 { $subsections
  68     file-info
  69     link-info
  70     file-exists?
  71     directory?
  72     regular-file?
  73     symbolic-link?
  74 }
  75 "File types:"
  76 { $subsections "file-types" }
  77 "File system metadata:"
  78 { $subsections
  79     file-system-info
  80     file-systems
  81 }
  82 "File permissions:"
  83 { $subsections
  84     file-readable?
  85     file-writable?
  86     file-executable?
  87 } ;
  88
  89 ABOUT: "io.files.info"