basis/tools/completion/completion-docs.factor

   1 USING: help.markup help.syntax strings generic vectors assocs
   2 math make ;
   3 IN: tools.completion
   4
   5 ARTICLE: "tools.completion" "Fuzzy completion"
   6 "Various developer tools make use of a general-purpose fuzzy completion algorithm."
   7 $nl
   8 "The main entry point:"
   9 { $subsections completions }
  10 "The words used to implement the algorithm can be called as well, for finer control over fuzzy matching:"
  11 { $subsections
  12     fuzzy
  13     runs
  14     score
  15     complete
  16     rank-completions
  17 } ;
  18
  19 ABOUT: "tools.completion"
  20
  21 HELP: fuzzy
  22 { $values { "full" string } { "short" string } { "indices" vector } }
  23 { $description "If " { $snippet "short" } " can be obtained from " { $snippet "full" } " by removing subsequences, then outputs the index of every character from " { $snippet "short" } " in " { $snippet "full" } ", otherwise outputs " { $link f } "." } ;
  24
  25 HELP: runs
  26 { $values { "seq" "a sequence of integers" } { "newseq" "a sequence of sequences of integers" } }
  27 { $description "Groups subsequences of consecutive integers." }
  28 { $examples
  29     { $example "USING: prettyprint sequences tools.completion ;" "{ 1 2 3 5 6 9 10 } runs [ { } like ] map ." "{ { 1 2 3 } { 5 6 } { 9 10 } }" }
  30 } ;
  31
  32 HELP: score
  33 { $values { "full" string } { "fuzzy" "a sequence of sequences of integers" } { "n" integer } }
  34 { $description "Ranks " { $snippet "fuzzy" } " by how closely it approximates the sequence " { $snippet "{ { 0 ... n-1 } }" } " where " { $snippet "n" } " is the length of " { $snippet "full" } "." } ;
  35
  36 HELP: rank-completions
  37 { $values { "results" "an alist" } { "newresults" "an alist" } }
  38 { $description "Sorts " { $snippet "results" } " by the first element of each pair, and discards the low 33% of the results." } ;
  39
  40 HELP: complete
  41 { $values { "full" string } { "short" string } { "score" "a rational number between 0 and 1" } }
  42 { $description "Ranks how close " { $snippet "short" } " is to " { $snippet "full" } " by edit distance." } ;
  43
  44 HELP: completion
  45 { $values { "short" string } { "candidate" "a pair " { $snippet "{ obj full }" } } { "score" number } }
  46 { $description "Outputs a score for matching two elements indicating how close " { $snippet "short" } " is to " { $snippet "full" } " by edit distance" } ;
  47
  48 HELP: completion,
  49 { $values { "short" string } { "candidate" "a pair " { $snippet "{ obj full }" } } }
  50 { $description
  51     "Adds the result of " { $link completion }
  52     " to the end of the sequence being constructed by " { $link make }
  53     " if the score is positive."
  54 } ;
  55
  56 HELP: completions
  57 { $values { "short" string } { "candidates" "a sequence of pairs of the shape " { $snippet "{ obj full }" } } { "seq" "a sequence of pairs of the shape " { $snippet "{ score obj }" } } }
  58 { $description "Calls " { $link completion } " to produce a sequence of " { $snippet "{ score obj }" } " pairs, then calls " { $link rank-completions } " to sort them and discard the low 33%." } ;