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

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel quotations sequences ;
   4 IN: io.directories.search
   5
   6 HELP: each-file
   7 { $values
   8      { "path" "a pathname string" } { "bfs?" "a boolean, breadth-first or depth-first" } { "quot" quotation }
   9 }
  10 { $description "Performs a directory traversal, breadth-first or depth-first, and calls the quotation on the full pathname of each file." }
  11 { $examples
  12     { $unchecked-example "USING: sequences io.directories.search ;"
  13         "\"resource:misc\" t [ . ] each-file"
  14         "! Recursive directory listing prints here"
  15     }
  16 } ;
  17
  18 HELP: recursive-directory-files
  19 { $values
  20      { "path" "a pathname string" } { "bfs?" "a boolean, breadth-first or depth-first" }
  21      { "paths" "a sequence of pathname strings" }
  22 }
  23 { $description "Traverses a directory path recursively and returns a sequence of files in a breadth-first or depth-first manner." } ;
  24
  25 HELP: recursive-directory-entries
  26 { $values
  27      { "path" "a pathname string" } { "bfs?" "a boolean, breadth-first or depth-first" }
  28      { "directory-entries" "a sequence of directory-entries" }
  29 }
  30 { $description "Traverses a directory path recursively and returns a sequence of directory-entries in a breadth-first or depth-first manner." } ;
  31
  32 HELP: find-file
  33 { $values
  34      { "path" "a pathname string" } { "bfs?" "a boolean, breadth-first or depth-first" } { "quot" quotation }
  35      { "path/f" "a pathname string or f" }
  36 }
  37 { $description "Finds the first file in the input directory matching the predicate quotation in a breadth-first or depth-first traversal." } ;
  38
  39 HELP: find-in-directories
  40 { $values
  41      { "directories" "a sequence of pathnames" } { "bfs?" "a boolean, breadth-first or depth-first" } { "quot" quotation }
  42      { "path'/f" "a pathname string or f" }
  43 }
  44 { $description "Finds the first file in the input directories matching the predicate quotation in a breadth-first or depth-first traversal." } ;
  45
  46 HELP: find-all-files
  47 { $values
  48      { "path" "a pathname string" } { "quot" quotation }
  49      { "paths/f" "a sequence of pathname strings or f" }
  50 }
  51 { $description "Recursively finds all files in the input directory matching the predicate quotation." } ;
  52
  53 HELP: find-all-in-directories
  54 { $values
  55      { "directories" "a sequence of directory paths" } { "quot" quotation }
  56      { "paths/f" "a sequence of pathname strings or f" }
  57 }
  58 { $description "Finds all files in the input directories matching the predicate quotation in a breadth-first or depth-first traversal." } ;
  59
  60 HELP: find-by-extension
  61 { $values
  62     { "path" "a pathname string" } { "extension" "a file extension" }
  63     { "seq" sequence }
  64 }
  65 { $description "Searches a directory for all files with the given extension. File extension and filenames are converted to lower-case and compared using the " { $link tail? } " word. The file extension should contain the period." }
  66 { $examples
  67     { $unchecked-example
  68         "USING: io.directories.search ;"
  69         "\"/\" \".mp3\" find-by-extension"
  70     }
  71 } ;
  72
  73 HELP: find-by-extensions
  74 { $values
  75     { "path" "a pathname string" } { "extensions" "a sequence of file extensions" }
  76     { "seq" sequence }
  77 }
  78 { $description "Searches a directory for all files in the given list of extensions. File extensions and filenames are converted to lower-case and compared using the " { $link tail? } " word. File extensions should contain the period." }
  79 { $examples
  80     { $unchecked-example
  81         "USING: io.directories.search ;"
  82         "\"/\" { \".jpg\" \".gif\" \".tiff\" \".png\" \".bmp\" } find-by-extensions"
  83     }
  84 } ;
  85
  86 { find-file find-all-files find-in-directories find-all-in-directories } related-words
  87
  88 ARTICLE: "io.directories.search" "Searching directories"
  89 "The " { $vocab-link "io.directories.search" } " vocabulary contains words used for recursively iterating over a directory and for finding files in a directory tree." $nl
  90 "Traversing directories:"
  91 { $subsections
  92     recursive-directory-files
  93     recursive-directory-entries
  94     each-file
  95 }
  96 "Finding files by name:"
  97 { $subsections
  98     find-file
  99     find-all-files
 100     find-in-directories
 101     find-all-in-directories
 102 }
 103 "Finding files by extension:"
 104 { $subsections
 105     find-by-extension
 106     find-by-extensions
 107 } ;
 108
 109 ABOUT: "io.directories.search"