extra/graphviz/builder/builder-docs.factor

   1 ! Copyright (C) 2011 Alex Vondrak.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: alien graphviz graphviz.attributes graphviz.ffi
   4 help.markup help.syntax kernel ;
   5 IN: graphviz.builder
   6
   7 HELP: build-alien
   8 { $values
   9     { "Agraph_t*" c-ptr }
  10     { "graph" graph }
  11 }
  12 { $description "Constructs a C representation of the given " { $link graph } " in memory by using the " { $vocab-link "graphviz.ffi" } " vocabulary to destructively modify " { $snippet "Agraph_t*" } " (a " { $link c-ptr } " created by " { $link agopen } ")." }
  13 { $notes "User code should not call this word directly. Use the " { $vocab-link "graphviz.render" } " vocabulary instead." }
  14 { $errors "Throws " { $link non-graph-error } " if applied to anything other than an instance of " { $link graph } "."
  15 $nl
  16 "Throws " { $link improper-statement-error } " if any of the " { $link graph } "'s " { $slot "statements" } " is not an instance of:"
  17 { $list { $link subgraph } { $link node } { $link edge } { $link graph-attributes } { $link node-attributes } { $link edge-attributes } }
  18 }
  19 ;
  20
  21 HELP: improper-statement-error
  22 { $values
  23     { "obj" object }
  24 }
  25 { $error-description "Thrown if, in a call to " { $link build-alien } ", any of a " { $link graph } "'s " { $snippet "statements" } " is not an instance of:" { $list { $link subgraph } { $link node } { $link edge } { $link graph-attributes } { $link node-attributes } { $link edge-attributes } } }
  26 ;
  27
  28 HELP: non-graph-error
  29 { $values
  30     { "obj" object }
  31 }
  32 { $error-description "Thrown if " { $link build-alien } " is applied to an object that is not an instance of " { $link graph } "." } ;
  33
  34 ARTICLE: "graphviz.builder" "Constructing C versions of Graphviz graphs"
  35 "The " { $vocab-link "graphviz.builder" } " vocabulary implements words to convert a " { $link graph } " object into its equivalent C representation in " { $emphasis "libgvc" } " and " { $emphasis "libgraph" } " (see the " { $vocab-link "graphviz.ffi" } " vocabulary)."
  36 $nl
  37 "These are low-level words used to implement the " { $vocab-link "graphviz.render" } " vocabulary. As such, user code should not use " { $vocab-link "graphviz.builder" } " directly."
  38 $nl
  39 "The main word:"
  40 { $subsections build-alien }
  41 "Errors that might be thrown:"
  42 { $subsections non-graph-error improper-statement-error }
  43 ;
  44
  45 ABOUT: "graphviz.builder"