core/source-files/source-files-docs.factor

   1 USING: help.markup help.syntax vocabs.loader io.files strings
   2 definitions quotations ;
   3 IN: source-files
   4
   5 ARTICLE: "source-files" "Source files"
   6 "Words in the " { $vocab-link "source-files" } " vocabulary are used to keep track of loaded source files. This is used to implement features such as " { $link refresh-all } "."
   7 $nl
   8 "The source file database:"
   9 { $subsection source-files }
  10 "The class of source files:"
  11 { $subsection source-file }
  12 "Testing if a source file has been changed on disk:"
  13 { $subsection source-modified? }
  14 "Words intended for the parser:"
  15 { $subsection record-modified }
  16 { $subsection record-checksum }
  17 { $subsection record-form }
  18 { $subsection xref-source }
  19 { $subsection unxref-source }
  20 "Removing a source file from the database:"
  21 { $subsection forget-source }
  22 "Updating the database:"
  23 { $subsection reset-checksums }
  24 "The " { $link pathname } " class implements the definition protocol by working with the corresponding source file; see " { $link "definitions" } "." ;
  25
  26 ABOUT: "source-files"
  27
  28 HELP: source-files
  29 { $var-description "An assoc mapping pathname strings to " { $link source-file } " instances, representing loaded source files." } ;
  30
  31 HELP: source-file
  32 { $values { "path" "a pathname string" } { "source-file" source-file } }
  33 { $description "Outputs the source file associated to a path name, creating the source file first if it doesn't exist. Source files are retained in the " { $link source-files } " variable." }
  34 { $class-description "Instances retain information about loaded source files, and have the following slots:"
  35     { $list
  36         { { $link source-file-path } " - a pathname string." }
  37         { { $link source-file-modified } " - the result of " { $link file-modified } " at the time the source file was most recently loaded." }
  38         { { $link source-file-checksum } " - the CRC32 checksum of the source file's contents at the time it was most recently loaded." }
  39         { { $link source-file-uses } " - an assoc whose keys are words referenced from this source file's top level form." }
  40         { { $link source-file-definitions } " - an assoc whose keys are definitions defined in this source file." }
  41     }
  42 } ;
  43
  44 HELP: source-modified?
  45 { $values { "path" "a pathname string" } { "?" "a boolean" } }
  46 { $description "Tests if the source file has been modified since it was last loaded. This compares the file's modification time and CRC32 checksum of the file's contents against previously-recorded values." } ;
  47
  48 HELP: record-modified
  49 { $values { "source-file" source-file } }
  50 { $description "Records the modification time of the source file." }
  51 $low-level-note ;
  52
  53 HELP: record-checksum
  54 { $values { "source-file" source-file } { "contents" string } }
  55 { $description "Records the CRC32 checksm of the source file's contents." }
  56 $low-level-note ;
  57
  58 HELP: xref-source
  59 { $values { "source-file" source-file } }
  60 { $description "Adds the source file to the " { $link crossref } " graph enabling words to find source files which reference them in their top level forms." }
  61 $low-level-note ;
  62
  63 HELP: unxref-source
  64 { $values { "source-file" source-file } }
  65 { $description "Removes the source file from the " { $link crossref } " graph." }
  66 $low-level-note ;
  67
  68 HELP: xref-sources
  69 { $description "Adds all loaded source files to the " { $link crossref } " graph. This is done during bootstrap." }
  70 $low-level-note ;
  71
  72 HELP: record-form
  73 { $values { "quot" quotation } { "source-file" source-file } }
  74 { $description "Records usage information for a source file's top level form." }
  75 $low-level-note ;
  76
  77 HELP: reset-checksums
  78 { $description "Resets recorded modification times and CRC32 checksums for all loaded source files, creating a checkpoint for " { $link refresh } "." } ;
  79
  80 HELP: forget-source
  81 { $values { "path" "a pathname string" } }
  82 { $description "Forgets all information known about a source file." } ;