extra/lint/vocabs/vocabs-docs.factor

   1 ! Copyright (C) 2022 CapitalEx
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: assocs hashtables help.markup help.syntax io kernel
   4 sequences strings ;
   5 IN: lint.vocabs
   6
   7 HELP: find-unused
   8 { $values
   9     { "name" "a vocab name string" }
  10     { "seq" sequence }
  11 }
  12 { $description
  13     "Finds unusued imports in the given vocab name. Returing the result as a " { $link sequence } "."
  14 }
  15 { $examples
  16     { $example "USING: lint.vocabs prettyprint ;"
  17         "\"lint.vocabs\" find-unused ."
  18         "{ }"
  19     }
  20 } ;
  21
  22 HELP: find-unused-in-file
  23 { $values
  24     { "path" "a pathname string" }
  25     { "seq" sequence }
  26 }
  27 { $description
  28     "Finds unused imports in the given file. Returing the result as a " { $link sequence } "."
  29 }
  30 { $examples
  31     { $example "USING: lint.vocabs prettyprint ;"
  32         "\"vocab:lint/vocabs/vocabs.factor\" find-unused-in-file ."
  33         "{ }"
  34     }
  35 } ;
  36
  37 HELP: find-unused-in-string
  38 { $values
  39     { "string" string }
  40     { "seq" sequence }
  41 }
  42 { $description
  43     "Finds unused imports in the given " { $link string } ". Returing the result as a " { $link sequence } "."
  44 } ;
  45
  46 HELP: find-unused.
  47 { $values
  48     { "name" "a vocab name string" }
  49 }
  50 { $description
  51     "Finds unused imports in given vocab and outputs it to the current " { $link output-stream } "."
  52 }
  53 { $examples
  54     { $example "USING: lint.vocabs ;"
  55         "\"lint.vocabs\" find-unused."
  56         "No unused vocabs found in lint.vocabs."
  57     }
  58 } ;
  59
  60 HELP: get-imported-words
  61 { $values
  62     { "string" string }
  63     { "hashtable" hashtable }
  64 }
  65 { $description
  66     "Gets all words that have been imported with " { $link \ USE: } " and " { $link \ USING: } " in the given string."
  67 } ;
  68
  69 HELP: get-vocabs
  70 { $values
  71     { "string" string }
  72     { "seq" sequence }
  73 }
  74 { $description
  75     "Gets all the vocabularies imported in the given string."
  76 } ;
  77
  78 HELP: get-words
  79 { $values
  80     { "name" "a vocab name string" }
  81     { "assoc" assoc }
  82 }
  83 { $description
  84     "Gets all the words used in a given vocabulary."
  85 }
  86 { $examples
  87     { $example "USING: lint.vocabs prettyprint ;"
  88         "\"lint.vocabs\" get-words ."
  89 "{
  90     \"lint.vocabs\"
  91     {
  92         \"get-vocabs\"
  93         \"get-words\"
  94         \"find-unused-in-file\"
  95         \"get-imported-words\"
  96         \"find-unused-in-string\"
  97         \"find-unused.\"
  98         \"find-unused\"
  99     }
 100 }"
 101     }
 102 } ;
 103
 104 ARTICLE: "lint.vocabs" "The Unused Vocabulary Linter"
 105 "The " { $vocab-link "lint.vocabs" } " vocabulary implements a set of words designed to find unused imports."
 106 "It attempts to ignore USE: and USING: that are a part of a string, postponed with either POSTPONE: or \\, and"
 107 "contained inside a " { $link "regexp" } "."
 108 $nl
 109 "It can sometimes be easy to lose track of what vocabularies you've imported while iterating over ideas. So to"
 110 "find any vocabularies you feel are unused, you can run:"
 111 $nl
 112 { $example
 113     "USING: lint.vocabs ;"
 114     "\"lint.vocabs\" find-unused."
 115     "No unused vocabs found in lint.vocabs."
 116 }
 117 ;
 118
 119 ABOUT: "lint.vocabs"