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