core/queues/queues-docs.factor

   1 USING: help.markup help.syntax kernel ;
   2 IN: queues
   3
   4 ARTICLE: "queues" "Queues"
   5 "Last-in-first-out queues are defined in the " { $vocab-link "queues" } " vocabulary."
   6 $nl
   7 "Queues are a class."
   8 { $subsection queue }
   9 { $subsection queue? }
  10 { $subsection <queue> }
  11 "Testing queues:"
  12 { $subsection queue-empty? }
  13 "Adding elements:"
  14 { $subsection deque }
  15 "Removing elements:"
  16 { $subsection enque }
  17 { $subsection clear-queue }
  18 { $subsection queue-each }
  19 "An example:"
  20 { $code
  21     "<queue> \"q\" set"
  22     "5 \"q\" get enque"
  23     "3 \"q\" get enque"
  24     "7 \"q\" get enque"
  25     "\"q\" get deque ."
  26     "  5"
  27     "\"q\" get deque ."
  28     "  3"
  29     "\"q\" get deque ."
  30     "  7"
  31 } ;
  32
  33 ABOUT: "queues"
  34
  35 HELP: queue
  36 { $class-description "A simple first-in-first-out queue. See " { $link "queues" } "." } ;
  37
  38 HELP: entry
  39 { $class-description "The class of entries in a " { $link queue } ". Each entry holds an object and a reference to the next entry." } ;
  40
  41 HELP: <entry>
  42 { $values { "obj" object } { "entry" entry } }
  43 { $description "Creates a new queue entry." }
  44 { $notes "This word is a factor of " { $link enque } "." } ;
  45
  46 HELP: <queue>
  47 { $values { "queue" queue } }
  48 { $description "Makes a new queue with no elements." } ;
  49
  50 HELP: queue-empty?
  51 { $values { "queue" queue } { "?" "a boolean" } }
  52 { $description "Tests if a queue contains no elements." } ;
  53
  54 HELP: deque
  55 { $values { "queue" queue } { "elt" object } }
  56 { $description "Removes an element from the front of the queue." }
  57 { $errors "Throws an " { $link empty-queue-error } " if the queue has no entries." }
  58 { $side-effects "queue" } ;
  59
  60 HELP: enque
  61 { $values { "elt" object } { "queue" queue } }
  62 { $description "Adds an element to the back of the queue." }
  63 { $side-effects "queue" } ;
  64
  65 HELP: empty-queue-error
  66 { $description "Throws an " { $link empty-queue-error } "." }
  67 { $error-description "Thrown by " { $link deque } " if the queue has no entries." } ;
  68
  69 HELP: clear-queue
  70 { $values { "queue" queue } }
  71 { $description "Removes all entries from the queue." }
  72 { $side-effects "queue" } ;
  73
  74 HELP: queue-each
  75 { $values { "queue" queue } { "quot" "a quotation with stack effect " { $snippet "( obj -- )" } } }
  76 { $description "Applies the quotation to each entry in the queue, starting from the least recently added entry, clearing the queue in the process." }
  77 { $side-effects "queue" } ;