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

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: classes help.markup help.syntax io.streams.string
   4 strings math calendar io.files.info io.files.info.unix ;
   5 IN: io.files.unix
   6
   7 HELP: file-group-id
   8 { $values
   9      { "path" "a pathname string" }
  10      { "gid" integer } }
  11 { $description "Returns the group id for a given file." } ;
  12
  13 HELP: file-group-name
  14 { $values
  15      { "path" "a pathname string" }
  16      { "string" string } }
  17 { $description "Returns the group name for a given file." } ;
  18
  19 HELP: file-permissions
  20 { $values
  21      { "path" "a pathname string" }
  22      { "n" integer } }
  23 { $description "Returns the Unix file permissions for a given file." } ;
  24
  25 HELP: file-user-name
  26 { $values
  27      { "path" "a pathname string" }
  28      { "string" string } }
  29 { $description "Returns the user-name for a given file." } ;
  30
  31 HELP: file-user-id
  32 { $values
  33      { "path" "a pathname string" }
  34      { "uid" integer } }
  35 { $description "Returns the user id for a given file." } ;
  36
  37 HELP: group-execute?
  38 { $values
  39      { "obj" "a pathname string or an integer" }
  40      { "?" "a boolean" } }
  41 { $description "Tests whether the " { $snippet "group execute" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  42
  43 HELP: group-read?
  44 { $values
  45      { "obj" "a pathname string, file-info object, or an integer" }
  46      { "?" "a boolean" } }
  47 { $description "Tests whether the " { $snippet "group read" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  48
  49 HELP: group-write?
  50 { $values
  51      { "obj" "a pathname string, file-info object, or an integer" }
  52      { "?" "a boolean" } }
  53 { $description "Tests whether the " { $snippet "group write" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  54
  55 HELP: other-execute?
  56 { $values
  57      { "obj" "a pathname string, file-info object, or an integer" }
  58      { "?" "a boolean" } }
  59 { $description "Tests whether the " { $snippet "other execute" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  60
  61 HELP: other-read?
  62 { $values
  63      { "obj" "a pathname string, file-info object, or an integer" }
  64      { "?" "a boolean" } }
  65 { $description "Tests whether the " { $snippet "other read" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  66
  67 HELP: other-write?
  68 { $values
  69      { "obj" "a pathname string, file-info object, or an integer" }
  70      { "?" "a boolean" } }
  71 { $description "Tests whether the " { $snippet "other write" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  72
  73 HELP: set-file-access-time
  74 { $values
  75      { "path" "a pathname string" } { "timestamp" timestamp } }
  76 { $description "Sets a file's last access timestamp." } ;
  77
  78 HELP: set-file-group
  79 { $values
  80      { "path" "a pathname string" } { "string/id" "a string or a group id" } }
  81 { $description "Sets a file's group id from the given group id or group name." } ;
  82
  83 HELP: set-file-ids
  84 { $values
  85      { "path" "a pathname string" } { "uid" integer } { "gid" integer } }
  86 { $description "Sets the user id and group id of a file with a single library call." } ;
  87
  88 HELP: set-file-permissions
  89 { $values
  90      { "path" "a pathname string" } { "n" "an integer, interepreted as a string of bits" } }
  91 { $description "Sets the file permissions for a given file with the supplied Unix permissions integer. Supplying an octal number with " { $link POSTPONE: OCT: } " is recommended." }
  92 { $examples "Using the tradidional octal value:"
  93     { $unchecked-example "USING: io.files.unix kernel ;"
  94         "\"resource:license.txt\" OCT: 755 set-file-permissions"
  95         ""
  96     }
  97     "Higher-level, setting named bits:"
  98     { $unchecked-example "USING: io.files.unix kernel math.bitwise ;"
  99     "\"resource:license.txt\""
 100     "{ USER-ALL GROUP-READ GROUP-EXECUTE OTHER-READ OTHER-EXECUTE }"
 101     "flags set-file-permissions"
 102     "" }
 103 } ;
 104
 105 HELP: set-file-times
 106 { $values
 107      { "path" "a pathname string" } { "timestamps" "an array of two timestamps" } }
 108 { $description "Sets the access and write timestamps for a file as provided in the input array. A value of " { $link f } " provided for either of the timestamps will not change that timestamp." } ;
 109
 110 HELP: set-file-user
 111 { $values
 112      { "path" "a pathname string" } { "string/id" "a string or a user id" } }
 113 { $description "Sets a file's user id from the given user id or user-name." } ;
 114
 115 HELP: set-file-modified-time
 116 { $values
 117      { "path" "a pathname string" } { "timestamp" timestamp } }
 118 { $description "Sets a file's last modified timestamp, or write timestamp." } ;
 119
 120 HELP: set-gid
 121 { $values
 122      { "path" "a pathname string" } { "?" "a boolean" } }
 123 { $description "Sets the " { $snippet "gid" } " bit of a file to true or false." } ;
 124
 125 HELP: gid?
 126 { $values
 127      { "obj" "a pathname string, file-info object, or an integer" }
 128      { "?" "a boolean" } }
 129 { $description "Tests whether the " { $snippet "gid" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 130
 131 HELP: set-group-execute
 132 { $values
 133      { "path" "a pathname string" } { "?" "a boolean" } }
 134 { $description "Sets the " { $snippet "group execute" } " bit of a file to true or false." } ;
 135
 136 HELP: set-group-read
 137 { $values
 138      { "path" "a pathname string" } { "?" "a boolean" } }
 139 { $description "Sets the " { $snippet "group read" } " bit of a file to true or false." } ;
 140
 141 HELP: set-group-write
 142 { $values
 143      { "path" "a pathname string" } { "?" "a boolean" } }
 144 { $description "Sets the " { $snippet "group write" } " bit of a file to true or false." } ;
 145
 146 HELP: set-other-execute
 147 { $values
 148      { "path" "a pathname string" } { "?" "a boolean" } }
 149 { $description "Sets the " { $snippet "other execute" } " bit of a file to true or false." } ;
 150
 151 HELP: set-other-read
 152 { $values
 153      { "path" "a pathname string" } { "?" "a boolean" } }
 154 { $description "Sets the " { $snippet "other read" } " bit of a file to true or false." } ;
 155
 156 HELP: set-other-write
 157 { $values
 158      { "path" "a pathname string" } { "?" "a boolean" } }
 159 { $description "Sets the " { $snippet "other execute" } " bit of a file to true or false." } ;
 160
 161 HELP: set-sticky
 162 { $values
 163      { "path" "a pathname string" } { "?" "a boolean" } }
 164 { $description "Sets the " { $snippet "sticky" } " bit of a file to true or false." } ;
 165
 166 HELP: sticky?
 167 { $values
 168      { "obj" "a pathname string, file-info object, or an integer" }
 169      { "?" "a boolean" } }
 170 { $description "Tests whether the " { $snippet "sticky" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 171
 172 HELP: set-uid
 173 { $values
 174      { "path" "a pathname string" } { "?" "a boolean" } }
 175 { $description "Sets the " { $snippet "uid" } " bit of a file to true or false." } ;
 176
 177 HELP: uid?
 178 { $values
 179      { "obj" "a pathname string, file-info object, or an integer" }
 180      { "?" "a boolean" } }
 181 { $description "Tests whether the " { $snippet "uid" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 182
 183 HELP: set-user-execute
 184 { $values
 185      { "path" "a pathname string" } { "?" "a boolean" } }
 186 { $description "Sets the " { $snippet "user execute" } " bit of a file to true or false." } ;
 187
 188 HELP: set-user-read
 189 { $values
 190      { "path" "a pathname string" } { "?" "a boolean" } }
 191 { $description "Sets the " { $snippet "user read" } " bit of a file to true or false." } ;
 192
 193 HELP: set-user-write
 194 { $values
 195      { "path" "a pathname string" } { "?" "a boolean" } }
 196 { $description "Sets the " { $snippet "user write" } " bit of a file to true or false." } ;
 197
 198 HELP: user-execute?
 199 { $values
 200      { "obj" "a pathname string, file-info object, or an integer" }
 201      { "?" "a boolean" } }
 202 { $description "Tests whether the " { $snippet "user execute" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 203
 204 HELP: user-read?
 205 { $values
 206      { "obj" "a pathname string, file-info object, or an integer" }
 207      { "?" "a boolean" } }
 208 { $description "Tests whether the " { $snippet "user read" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 209
 210 HELP: user-write?
 211 { $values
 212      { "obj" "a pathname string, file-info object, or an integer" }
 213      { "?" "a boolean" } }
 214 { $description "Tests whether the " { $snippet "user write" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 215
 216 ARTICLE: "unix-file-permissions" "Unix file permissions"
 217 "Reading all file permissions:"
 218 { $subsection file-permissions }
 219 "Reading individual file permissions:"
 220 { $subsection uid? }
 221 { $subsection gid? }
 222 { $subsection sticky? }
 223 { $subsection user-read? }
 224 { $subsection user-write? }
 225 { $subsection user-execute? }
 226 { $subsection group-read? }
 227 { $subsection group-write? }
 228 { $subsection group-execute? }
 229 { $subsection other-read? }
 230 { $subsection other-write? }
 231 { $subsection other-execute? }
 232 "Writing all file permissions:"
 233 { $subsection set-file-permissions }
 234 "Writing individual file permissions:"
 235 { $subsection set-uid }
 236 { $subsection set-gid }
 237 { $subsection set-sticky }
 238 { $subsection set-user-read }
 239 { $subsection set-user-write }
 240 { $subsection set-user-execute }
 241 { $subsection set-group-read }
 242 { $subsection set-group-write }
 243 { $subsection set-group-execute }
 244 { $subsection set-other-read }
 245 { $subsection set-other-write }
 246 { $subsection set-other-execute } ;
 247
 248 ARTICLE: "unix-file-timestamps" "Unix file timestamps"
 249 "To read file times, use the accessors on the object returned by the " { $link file-info } " word." $nl
 250 "Setting multiple file times:"
 251 { $subsection set-file-times }
 252 "Setting just the last access time:"
 253 { $subsection set-file-access-time }
 254 "Setting just the last modified time:"
 255 { $subsection set-file-modified-time } ;
 256
 257
 258 ARTICLE: "unix-file-ids" "Unix file user and group ids"
 259 "Reading file user data:"
 260 { $subsection file-user-id }
 261 { $subsection file-user-name }
 262 "Setting file user data:"
 263 { $subsection set-file-user }
 264 "Reading file group data:"
 265 { $subsection file-group-id }
 266 { $subsection file-group-name }
 267 "Setting file group data:"
 268 { $subsection set-file-group } ;
 269
 270
 271 ARTICLE: "io.files.info.unix" "Unix file attributes"
 272 "The " { $vocab-link "io.files.info.unix" } " vocabulary implements a high-level way to set Unix-specific permissions, timestamps, and user and group IDs for files."
 273 { $subsection "unix-file-permissions" }
 274 { $subsection "unix-file-timestamps" }
 275 { $subsection "unix-file-ids" } ;
 276
 277 ABOUT: "io.files.info.unix"