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

   1 USING: help.markup help.syntax vocabs.loader io.files strings
   2 definitions quotations compiler.units ;
   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 " { $link "tools.vocabs" } "."
   7 $nl
   8 "The source file database:"
   9 { $subsection source-files }
  10 "The class of source files:"
  11 { $subsection source-file }
  12 "Words intended for the parser:"
  13 { $subsection record-checksum }
  14 { $subsection record-form }
  15 { $subsection xref-source }
  16 { $subsection unxref-source }
  17 "Removing a source file from the database:"
  18 { $subsection forget-source }
  19 "Updating the database:"
  20 { $subsection reset-checksums }
  21 "The " { $link pathname } " class implements the definition protocol by working with the corresponding source file; see " { $link "definitions" } "." ;
  22
  23 ABOUT: "source-files"
  24
  25 HELP: source-files
  26 { $var-description "An assoc mapping pathname strings to " { $link source-file } " instances, representing loaded source files." } ;
  27
  28 HELP: source-file
  29 { $values { "path" "a pathname string" } { "source-file" source-file } }
  30 { $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." }
  31 { $class-description "Instances retain information about loaded source files, and have the following slots:"
  32     { $list
  33         { { $snippet "path" } " - a pathname string." }
  34         { { $snippet "checksum" } " - the CRC32 checksum of the source file's contents at the time it was most recently loaded." }
  35         { { $snippet "uses" } " - an assoc whose keys are words referenced from this source file's top level form." }
  36         { { $snippet "definitions" } " - a pair of assocs, containing definitions and classes defined in this source file, respectively" }
  37     }
  38 } ;
  39
  40 HELP: record-checksum
  41 { $values { "source-file" source-file } { "lines" "a sequence of strings" } }
  42 { $description "Records the CRC32 checksm of the source file's contents." }
  43 $low-level-note ;
  44
  45 HELP: xref-source
  46 { $values { "source-file" source-file } }
  47 { $description "Adds the source file to the " { $link crossref } " graph enabling words to find source files which reference them in their top level forms." }
  48 $low-level-note ;
  49
  50 HELP: unxref-source
  51 { $values { "source-file" source-file } }
  52 { $description "Removes the source file from the " { $link crossref } " graph." }
  53 $low-level-note ;
  54
  55 HELP: xref-sources
  56 { $description "Adds all loaded source files to the " { $link crossref } " graph. This is done during bootstrap." }
  57 $low-level-note ;
  58
  59 HELP: record-form
  60 { $values { "quot" quotation } { "source-file" source-file } }
  61 { $description "Records usage information for a source file's top level form." }
  62 $low-level-note ;
  63
  64 HELP: reset-checksums
  65 { $description "Resets recorded modification times and CRC32 checksums for all loaded source files, creating a checkpoint for " { $link "tools.vocabs" } "." } ;
  66
  67 HELP: forget-source
  68 { $values { "path" "a pathname string" } }
  69 { $description "Forgets all information known about a source file." }
  70 { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
  71
  72 HELP: record-definitions
  73 { $values { "file" source-file } }
  74 { $description "Records that all " { $link new-definitions } " were defined in " { $snippet "file" } "." } ;
  75
  76 HELP: rollback-source-file
  77 { $values { "file" source-file } }
  78 { $description "Records information to the source file after an incomplete parse which ended with an error." } ;
  79
  80 HELP: file
  81 { $var-description "Stores the " { $link source-file } " being parsed. The " { $snippet "path" } " of this object comes from the input parameter to " { $link with-source-file } "." } ;