basis/io/directories/hierarchy/hierarchy-docs.factor

   1 USING: help.markup help.syntax quotations io.pathnames ;
   2 IN: io.directories.hierarchy
   3
   4 HELP: directory-tree-files
   5 { $values { "path" "a pathname string" } { "seq" "a sequence of filenames" } }
   6 { $description "Outputs a sequence of all files and subdirectories inside the directory named by " { $snippet "path" } " or recursively inside its subdirectories." } ;
   7
   8 HELP: with-directory-tree-files
   9 { $values { "path" "a pathname string" } { "quot" quotation } }
  10 { $description "Calls the quotation with the recursive directory file names on the stack and with the directory set as the " { $link current-directory } ".  Restores the current directory after the quotation is called." } ;
  11
  12 HELP: delete-tree
  13 { $values { "path" "a pathname string" } }
  14 { $description "Deletes a file or directory, recursing into subdirectories." }
  15 { $errors "Throws an error if the deletion fails." }
  16 { $warning "Misuse of this word can lead to catastrophic data loss." } ;
  17
  18 HELP: copy-tree
  19 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
  20 { $description "Copies a directory tree recursively." }
  21 { $notes "This operation attempts to preserve original file attributes, however not all attributes may be preserved." }
  22 { $errors "Throws an error if the copy operation fails." } ;
  23
  24 HELP: copy-tree-into
  25 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
  26 { $description "Copies a directory tree to another directory, recursively." }
  27 { $errors "Throws an error if the copy operation fails." } ;
  28
  29 HELP: copy-trees-into
  30 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
  31 { $description "Copies a set of directory trees to another directory, recursively." }
  32 { $errors "Throws an error if the copy operation fails." } ;
  33
  34 ARTICLE: "io.directories.hierarchy" "Directory hierarchy manipulation"
  35 "The " { $vocab-link "io.directories.hierarchy" } " vocabulary defines words for operating on directory hierarchies recursively."
  36 $nl
  37 "There is a naming scheme used by " { $vocab-link "io.directories" } " and " { $vocab-link "io.directories.hierarchy" } ". Operations for deleting and copying files come in two forms:"
  38 { $list
  39     { "Words named " { $snippet { $emphasis "operation" } "-file" } " which work on regular files only." }
  40     { "Words named " { $snippet { $emphasis "operation" } "-tree" } " works on directory trees recursively, and also accepts regular files." }
  41 }
  42 "Listing directory trees recursively:"
  43 { $subsections
  44     directory-tree-files
  45     with-directory-tree-files
  46 }
  47 "Deleting directory trees recursively:"
  48 { $subsections delete-tree }
  49 "Copying directory trees recursively:"
  50 { $subsections
  51     copy-tree
  52     copy-tree-into
  53     copy-trees-into
  54 } ;
  55
  56 ABOUT: "io.directories.hierarchy"