basis/compiler/tree/builder/builder-docs.factor

   1 USING: compiler.tree help.markup help.syntax literals quotations sequences
   2 stack-checker.errors words ;
   3 IN: compiler.tree.builder
   4
   5 HELP: build-tree
   6 { $values { "word/quot" { $or word quotation } } { "nodes" "a sequence of nodes" } }
   7 { $description "Attempts to construct tree SSA IR from a quotation." }
   8 { $notes "This is the first stage of the compiler." }
   9 { $errors "Throws an " { $link inference-error } " if stack effect inference fails." } ;
  10
  11 HELP: build-sub-tree
  12 { $values { "in-d" "a sequence of values" } { "out-d" "a sequence of values" } { "word/quot" { $or word quotation } } { "nodes/f" { $maybe "a sequence of nodes" } } }
  13 { $description "Attempts to construct tree SSA IR from a quotation, starting with an initial data stack of values from the call site. Outputs " { $link f } " if stack effect inference fails." }
  14 { $examples
  15   { $unchecked-example
  16     ! The out-d numbers are unpredicable.
  17     "USING: compiler.tree.builder math prettyprint ;"
  18     "{ \"x\" } { \"y\" } [ 4 * ] build-sub-tree ."
  19     $[
  20         {
  21             "V{"
  22             "    T{ #push { literal 4 } { out-d { 1 } } }"
  23             "    T{ #call { word * } { in-d V{ \"x\" 1 } } { out-d { 2 } } }"
  24             "    T{ #copy { in-d V{ 2 } } { out-d { \"y\" } } }"
  25             "}"
  26         } "\n" join
  27     ]
  28   }
  29 } ;