(doc-group vm
  «VM-related functions.»)

(defdoc (environment)
  «Return the list of all bound top level symbols.»
  :doc-group vm
  :doc-see print-stack-trace)

(defdoc (vm-stats (io *io-out*))
  «Print various VM-related information, such as the number of GC
   calls so far, heap, and stack size, etc.»
  :doc-group vm)

(defdoc (tag-of v)
  «Return the internal VM tag of the value.»
  :doc-example
  «(tag-of 1)
   ; ↳ fixnum»
  :doc-example
  «(tag-of NIL)
   ; ↳ special»
  :doc-example
  «(tag-of "hello")
   ; ↳ cvalue»
  :doc-example
  «(tag-of (s32 1))
   ; ↳ unboxed»
  :doc-group vm
  :doc-see type-of)

(defdoc (builtin sym)
  «Return the builtin associated with the symbol.

   Throws an exception if no such builtin exists.»
  :doc-example
  «(builtin 'map)
   ; ↳ #fn(map)»
  :doc-example
  «(builtin 'print)
   ; ‼ arguments error: builtin "print" not found»
  :doc-group vm)

(defdoc (gc)
  «Force a garbage collection run.

   One does not need to execute this function manually since garbage
   collection will happen automatically, based on the amount of data
   allocated.»
  :doc-group vm
  :doc-see vm-stats)

(defdoc (*prompt*)
  «Function called by REPL to tell the user it's expecting input.

   The default `*prompt*` function prints `#;> `, which by itself is a
   commented-out expression, allowing the user to copy-paste the entire
   line (with the prompt) to reevaluate.»
  :doc-group vm
  :doc-see *interactive*)

(defdoc *interactive*
  «Variable indicating whether VM is running in "interactive" mode (`T`,
   REPL is active) or not (`NIL`, REPL is not active).

   Interactive mode can be forced by adding `-i` as the first command
   line argument.»
  :doc-group vm
  :doc-see *prompt*)

(defdoc *argv*
  «The list of command line arguments.

   If StreetLISP was started in interactive mode without a file specified
   for execution, `*argv*` will be a list containing just one value - the
   name of the `sl` executable.

   Otherwise, the file specified for execution and the rest of the remaining
   arguments will form the `*argv*` list.

   StreetLISP's own options, such as `-i` and `-H ...` will be stripped
   out in any case.»
  :doc-example
  «; $ sl -i -H 12345
   *argv*
   ; ↳ ("sl")»
  :doc-example
  «; $ sl script.sl -i abc
   *argv*
   ; ↳ ("script.sl" "-i" "abc")»
  :doc-group vm
  :doc-see *interactive*)