extra/generators/generators-docs.factor

   1 ! Copyright (C) 2023 Keldan Chapman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel math quotations sequences generators coroutines effects ;
   4 IN: generators
   5
   6 HELP: <generator>
   7 { $values
   8     { "quot" quotation }
   9     { "gen" generator }
  10 }
  11 { $description "Creates a generator object from an input quotation." } ;
  12
  13 HELP: ?next
  14 { $values
  15     { "gen" generator }
  16     { "val/f" { $maybe object } } { "end?" boolean }
  17 }
  18 { $description "A safe version of " { $link next } ". Also returns a boolean indicating whether the end of the generator was reached." } ;
  19
  20 HELP: ?next*
  21 { $values
  22     { "v" object } { "gen" generator }
  23     { "val/f" { $maybe object } } { "end?" boolean }
  24 }
  25 { $description "A safe version of " { $link next } ". Also returns a boolean indicating whether the end of the generator was reached." } ;
  26
  27 HELP: GEN:
  28 { $syntax "GEN: word ( stack -- generator ) definition... ;" }
  29 { $description "Creates a generator word in the current vocabulary. When executed, the word will capture its inputs from the stack and a generator object will be returned. The output of generator words must always be only a single value (the generator)." } ;
  30
  31 HELP: GEN::
  32 { $syntax "GEN:: word ( stack -- generator ) definition... ;" }
  33 { $description "Creates a generator word in the current vocabulary. When executed, the word's inputs will be captured from the stack and bound to them to lexical input variables from left to right. A generator object will be returned. The output of generator words must always be only a single value (the generator)." } ;
  34
  35
  36 HELP: assert-no-inputs
  37 { $values
  38     { "quot" quotation }
  39 }
  40 { $description "Throws a " { $link has-inputs } " error if the input quotation accepts inputs. Otherwise does nothing." } ;
  41
  42 HELP: catch-stop-generator
  43 { $values
  44     { "try" quotation } { "except" quotation }
  45 }
  46 { $description "Attempts to run the " { $snippet try } " quotation. If a " { $link stop-generator } " error is thrown, then the " { $snippet except } "quotation will be run instead." } ;
  47
  48 HELP: exhausted?
  49 { $values
  50     { "gen" generator } { "?" boolean }
  51 }
  52 { $description "Check whether a generator has already been exhausted." } ;
  53
  54 HELP: gen-coroutine
  55 { $values
  56     { "quot" quotation } { "gen" generator }
  57     { "co" coroutine }
  58 }
  59 { $description "Builds a coroutine from a quotation for use in a generator object. On termination of the quotation, the generator object will be marked as complete." } ;
  60
  61 HELP: generator
  62 { $class-description "A simplified coroutine which produces values as needed. " { $link stop-generator } " is thrown when no more values can be produced." } ;
  63
  64 HELP: has-inputs
  65 { $description "Throws a " { $link has-inputs } " error." }
  66 { $error-description "Indicates that a quotation incorrectly expects inputs." } ;
  67
  68 HELP: make-gen-quot
  69 { $values
  70     { "quot" quotation } { "effect" effect }
  71 }
  72 { $description "Prepares a quotation for use as a generator word." } ;
  73
  74 HELP: next
  75 { $values
  76     { "gen" generator }
  77     { "result" object }
  78 }
  79 { $description "Resume computation in the generator until the next value is produced." } ;
  80
  81 HELP: next*
  82 { $values
  83     { "v" object } { "gen" generator }
  84     { "result" object }
  85 }
  86 { $description "Pass a value into the generator, resuming computation until a value is produced." } ;
  87
  88 HELP: skip
  89 { $values
  90     { "gen" generator }
  91 }
  92 { $description "Resume computation until a value is produced. The value is discarded." } ;
  93
  94 HELP: skip*
  95 { $values
  96     { "v" object } { "gen" object }
  97 }
  98 { $description "Pass a value into the generator, resuming computation until a value is produced. The value is discarded." } ;
  99
 100 HELP: stop-generator
 101 { $description "Throws a " { $link stop-generator } " error." }
 102 { $error-description "Indicates that the generator has run out of values to produce" } ;
 103
 104 HELP: take
 105 { $values
 106     { "gen" generator } { "n" integer }
 107     { "seq" sequence }
 108 }
 109 { $description "Takes the next " { $snippet n } " values from the generator, collecting them into a sequence." } ;
 110
 111 HELP: take-all
 112 { $values
 113     { "gen" generator }
 114     { "seq" sequence }
 115 }
 116 { $description "Runs the generator until completion, collecting all yielded values into a sequence." } ;
 117
 118 HELP: yield
 119 { $values
 120     { "v" object }
 121 }
 122 { $description "Pause computation and yield a value to the caller." } ;
 123
 124 HELP: yield*
 125 { $values
 126     { "v" object }
 127     { "result" object }
 128 }
 129 { $description "Pause computation and yield a value to the caller, with the expectation for a value to be returned before computation is resumed." } ;
 130
 131 HELP: yield-from
 132 { $values
 133     { "gen" generator }
 134 }
 135 { $description "Delegate computation to the specified generator until it is exhausted, before resuming computation in the current generator." } ;
 136
 137 ARTICLE: "generators" "Generators"
 138 { $vocab-link "generators" }
 139 ;
 140
 141 ABOUT: "generators"