extra/graphviz/notation/notation-docs.factor

   1 ! Copyright (C) 2011 Alex Vondrak.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: graphviz graphviz.attributes help.markup help.syntax
   4 kernel present sequences ;
   5 IN: graphviz.notation
   6
   7 { add-edge [add-edge -- ~-- [-- } related-words
   8 { add-edge [add-edge -> ~-> [-> } related-words
   9 {
  10     [add-node [add-edge [-- [-> [node [edge [graph ];
  11 } related-words
  12
  13 HELP: --
  14 { $values
  15     { "graph" { $or graph subgraph } }
  16     { "tail" object }
  17     { "head" object }
  18     { "graph'" { $or graph subgraph } }
  19 }
  20 { $description "Shorthand for " { $link add-edge } ". Makes undirected " { $link graph } "s read more like graphs in the DOT language." }
  21 { $examples
  22     "Instead of writing"
  23     { $code
  24         "<graph>"
  25         "    1 2 add-edge"
  26         "    3 4 add-edge"
  27         "    5 6 add-edge"
  28     }
  29     "it looks better to write"
  30     { $code
  31         "<graph>"
  32         "    1 2 --"
  33         "    3 4 --"
  34         "    5 6 --"
  35     }
  36     "Compare this with the DOT language, where you'd write"
  37     { $code
  38         "graph {"
  39         "    1 -- 2"
  40         "    3 -- 4"
  41         "    5 -- 6"
  42         "}"
  43     }
  44 }
  45 ;
  46
  47 HELP: ->
  48 { $values
  49     { "graph" { $or graph subgraph } }
  50     { "tail" object }
  51     { "head" object }
  52     { "graph'" { $or graph subgraph } }
  53 }
  54 { $description "Shorthand for " { $link add-edge } ". Makes directed " { $link graph } "s read more like digraphs in the DOT language." }
  55 { $examples
  56     "Instead of writing"
  57     { $code
  58         "<digraph>"
  59         "    1 2 add-edge"
  60         "    3 4 add-edge"
  61         "    5 6 add-edge"
  62     }
  63     "it looks better to write"
  64     { $code
  65         "<digraph>"
  66         "    1 2 ->"
  67         "    3 4 ->"
  68         "    5 6 ->"
  69     }
  70     "Compare this with the DOT language, where you'd write"
  71     { $code
  72         "digraph {"
  73         "    1 -> 2"
  74         "    3 -> 4"
  75         "    5 -> 6"
  76         "}"
  77     }
  78 }
  79 ;
  80
  81 HELP: [--
  82 { $values
  83     { "tail" object }
  84     { "head" object }
  85     { "edge" edge }
  86 }
  87 { $description "Shorthand for " { $link <edge> } " to be used with " { $link ]; } " and attribute-setting generic words (see " { $link { "graphviz.notation" "=attrs" } } ") so that undirected " { $link graph } "s read more like graphs in the DOT language." }
  88 { $examples
  89   "Instead of writing"
  90   { $code
  91     "<graph>"
  92     "    1 2 <edge> \"red\" =color add"
  93   }
  94   "it looks better to write"
  95   { $code
  96     "<graph>"
  97     "    1 2 [-- \"red\" =color ];"
  98   }
  99   "Compare this with the DOT language, where you'd write"
 100   { $code
 101     "graph {"
 102     "    1 -- 2 [ color=\"red\" ];"
 103     "}"
 104   }
 105 }
 106 ;
 107
 108 HELP: [->
 109 { $values
 110     { "tail" object }
 111     { "head" object }
 112     { "edge" edge }
 113 }
 114 { $description "Shorthand for " { $link <edge> } " to be used with " { $link ]; } " and attribute-setting generic words (see " { $link { "graphviz.notation" "=attrs" } } ") so that directed " { $link graph } "s read more like digraphs in the DOT language." }
 115 { $examples
 116   "Instead of writing"
 117   { $code
 118     "<digraph>"
 119     "    1 2 <edge> \"red\" =color add"
 120   }
 121   "it looks better to write"
 122   { $code
 123     "<digraph>"
 124     "    1 2 [-> \"red\" =color ];"
 125   }
 126   "Compare this with the DOT language, where you'd write"
 127   { $code
 128     "digraph {"
 129     "    1 -> 2 [ color=\"red\" ];"
 130     "}"
 131   }
 132 }
 133 ;
 134
 135 HELP: ];
 136 { $values
 137     { "graph" { $or graph subgraph } }
 138     { "statement" object }
 139     { "graph'" { $or graph subgraph } }
 140 }
 141 { $description "Synonym for " { $link add } " meant to be the \"other half\" of various " { $vocab-link "graphviz.notation" } " words like " { $links [add-edge [add-node [graph } ", etc." }
 142 { $examples "Refer to the documentation for the complementary words listed below." }
 143 ;
 144
 145 HELP: [add-edge
 146 { $values
 147     { "tail" object }
 148     { "head" object }
 149     { "edge" edge }
 150 }
 151 { $description "Shorthand for " { $link <edge> } " to be used with " { $link ]; } " and attribute-setting generic words (see " { $link { "graphviz.notation" "=attrs" } } ") so that setting an " { $link edge } "'s " { $slot "attributes" } " reads more like the equivalent in the DOT language." }
 152 { $examples
 153   "Instead of writing"
 154   { $code
 155     "<graph>"
 156     "    1 2 <edge> \"red\" =color add"
 157   }
 158   "it looks better to write"
 159   { $code
 160     "<graph>"
 161     "    1 2 [add-edge \"red\" =color ];"
 162   }
 163   "Compare this with the DOT language, where you'd write"
 164   { $code
 165     "graph {"
 166     "    1 -- 2 [ color=\"red\" ];"
 167     "}"
 168   }
 169   $nl
 170   "This has the advantage over " { $link [-- } " and " { $link [-> } " of reading nicely for both directed " { $emphasis "and" } " undirected " { $link graph } "s."
 171 }
 172 ;
 173
 174 HELP: [add-node
 175 { $values
 176     { "id" object }
 177     { "node" node }
 178 }
 179 { $description "Shorthand for " { $link <node> } " to be used with " { $link ]; } " and attribute-setting generic words (see " { $link { "graphviz.notation" "=attrs" } } ") so that setting a " { $link node } "'s " { $slot "attributes" } " reads more like the equivalent in the DOT language." }
 180 { $examples
 181   "Instead of writing"
 182   { $code
 183     "<graph>"
 184     "    \"foo\" <node> \"red\" =color add"
 185   }
 186   "it looks better to write"
 187   { $code
 188     "<graph>"
 189     "    \"foo\" [add-node \"red\" =color ];"
 190   }
 191   "Compare this with the DOT language, where you'd write"
 192   { $code
 193     "graph {"
 194     "    foo [ color=\"red\" ];"
 195     "}"
 196   }
 197 }
 198 ;
 199
 200 HELP: [edge
 201 { $values
 202         { "attrs" edge-attributes }
 203 }
 204 { $description "Shorthand for " { $link <edge-attributes> } " to be used with " { $link ]; } " and attribute-setting generic words (see " { $link { "graphviz.notation" "=attrs" } } ") so that adding " { $link edge-attributes } " to a " { $link graph } " or " { $link subgraph } " reads more like the equivalent in the DOT language." }
 205 { $examples
 206   "Instead of writing"
 207   { $code
 208     "<graph>"
 209     "    <edge-attributes> \"red\" =color add"
 210   }
 211   "it looks better to write"
 212   { $code
 213     "<graph>"
 214     "    [edge \"red\" =color ];"
 215   }
 216   "Compare this with the DOT language, where you'd write"
 217   { $code
 218     "graph {"
 219     "    [edge color=\"red\" ];"
 220     "}"
 221   }
 222 }
 223 ;
 224
 225 HELP: [graph
 226 { $values
 227         { "attrs" graph-attributes }
 228 }
 229 { $description "Shorthand for " { $link <graph-attributes> } " to be used with " { $link ]; } " and attribute-setting generic words (see " { $link { "graphviz.notation" "=attrs" } } ") so that adding " { $link graph-attributes } " to a " { $link graph } " or " { $link subgraph } " reads more like the equivalent in the DOT language." }
 230 { $notes "This word is rendered redundant by the " { $link graph } " and " { $link subgraph } " methods defined by " { $vocab-link "graphviz.notation" } " for setting attributes. Sometimes it still might look better to delineate certain attribute-setting code." }
 231 { $examples
 232   "Instead of writing"
 233   { $code
 234     "<graph>"
 235     "    <graph-attributes> \"LR\" =rankdir \"blah\" =label add"
 236   }
 237   "it looks better to write"
 238   { $code
 239     "<graph>"
 240     "    [graph \"LR\" =rankdir \"blah\" =label ];"
 241   }
 242   "Compare this with the DOT language, where you'd write"
 243   { $code
 244     "graph {"
 245     "    [graph rankdir=\"LR\" label=\"blah\" ];"
 246     "}"
 247   }
 248   $nl
 249   "Of course, you could just write"
 250   { $code
 251     "<graph>"
 252     "    \"LR\" =rankdir"
 253     "    \"blah\" =label"
 254   }
 255   "Similarly, in the DOT language you could just write"
 256   { $code
 257     "graph {"
 258     "    rankdir=\"LR\""
 259     "    label=\"blah\""
 260     "}"
 261   }
 262 }
 263 ;
 264
 265 HELP: [node
 266 { $values
 267         { "attrs" node-attributes }
 268 }
 269 { $description "Shorthand for " { $link <node-attributes> } " to be used with " { $link ]; } " and attribute-setting generic words (see " { $link { "graphviz.notation" "=attrs" } } ") so that adding " { $link node-attributes } " to a " { $link graph } " or " { $link subgraph } " reads more like the equivalent in the DOT language." }
 270 { $examples
 271   "Instead of writing"
 272   { $code
 273     "<graph>"
 274     "    <node-attributes> \"red\" =color add"
 275   }
 276   "it looks better to write"
 277   { $code
 278     "<graph>"
 279     "    [node \"red\" =color ];"
 280   }
 281   "Compare this with the DOT language, where you'd write"
 282   { $code
 283     "graph {"
 284     "    [node color=\"red\" ];"
 285     "}"
 286   }
 287 }
 288 ;
 289
 290 HELP: ~--
 291 { $values
 292     { "graph" { $or graph subgraph } }
 293     { "nodes" sequence }
 294     { "graph'" { $or graph subgraph } }
 295 }
 296 { $description "Shorthand for " { $link add-path } ". Meant to be a Factor replacement for the DOT language's more verbose path notation." }
 297 { $examples
 298     "Instead of writing"
 299     { $code
 300       "<graph>"
 301       "    1 2 --"
 302       "    2 3 --"
 303       "    3 4 --"
 304     }
 305     "you can write"
 306     { $code
 307       "<graph>"
 308       "    { 1 2 3 4 } ~--"
 309     }
 310     "whereas in the DOT language you'd write"
 311     { $code
 312       "graph {"
 313       "    1 -- 2 -- 3 -- 4"
 314       "}"
 315     }
 316 }
 317 ;
 318
 319 HELP: ~->
 320 { $values
 321     { "graph" { $or graph subgraph } }
 322     { "nodes" sequence }
 323     { "graph'" { $or graph subgraph } }
 324 }
 325 { $description "Shorthand for " { $link add-path } ". Meant to be a Factor replacement for the DOT language's more verbose path notation." }
 326 { $examples
 327     "Instead of writing"
 328     { $code
 329       "<digraph>"
 330       "    1 2 ->"
 331       "    2 3 ->"
 332       "    3 4 ->"
 333     }
 334     "you can write"
 335     { $code
 336       "<digraph>"
 337       "    { 1 2 3 4 } ~->"
 338     }
 339     "whereas in the DOT language you'd write"
 340     { $code
 341       "digraph {"
 342       "    1 -> 2 -> 3 -> 4"
 343       "}"
 344     }
 345 }
 346 ;
 347
 348 ARTICLE: { "graphviz.notation" "=attrs" } "Notation for setting Graphviz attributes"
 349 "The " { $vocab-link "graphviz.notation" } " vocabulary provides words for setting Graphviz attributes in a way that looks similar to the DOT language (see " { $url "https://graphviz.org/content/dot-language" } ")."
 350 $nl
 351 "For every slot named, say, " { $snippet "attr" } " in the " { $link node-attributes } ", " { $link edge-attributes } ", and " { $link graph-attributes } " tuples, a generic word named " { $snippet "=attr" } " is defined with the stack effect " { $snippet "( graphviz-obj val -- graphviz-obj' )" } "."
 352 $nl
 353 "In each such " { $snippet "=attr" } " word, " { $snippet "val" } " must be an object supported by the " { $link present } " word, which is always called on " { $snippet "val" } " before it's stored in a slot."
 354 $nl
 355 "These generics will \"do the right thing\" in setting the corresponding attribute of " { $snippet "graphviz-obj" } "."
 356 $nl
 357 "For example, since " { $link graph-attributes } " has a " { $slot "label" } " slot, the generic " { $link =label } " is defined, along with methods so that if " { $snippet "graphviz-obj" } " is a..."
 358 { $list
 359     { "..." { $link graph } " or " { $link subgraph } ", a new " { $link graph-attributes } " instance is created, has its " { $slot "label" } " slot set to " { $snippet "val" } ", and is " { $link add } "ed to " { $snippet "graphviz-obj" } "." }
 360     { "..." { $link graph-attributes } " instance, its " { $slot "label" } " slot is set to " { $snippet "val" } "." }
 361 }
 362 $nl
 363 "Since " { $link edge-attributes } " has a " { $slot "label" } " slot, further methods are defined so that if " { $snippet "graphviz-obj" } " is an..."
 364 { $list
 365     { "..." { $link edge } ", its " { $slot "attributes" } " slot has its " { $slot "label" } " slot set to " { $snippet "val" } "." }
 366     { "..." { $link edge-attributes } " instance, its " { $slot "label" } " slot is set to " { $snippet "val" } "." }
 367 }
 368 $nl
 369 "Finally, since " { $link node-attributes } " has a " { $slot "label" } " slot, still more methods are defined so that if " { $snippet "graphviz-obj" } " is a..."
 370 { $list
 371     { "..." { $link node } ", its " { $slot "attributes" } " slot has its " { $slot "label" } " slot set to " { $snippet "val" } "." }
 372     { "..." { $link node-attributes } " instance, its " { $slot "label" } " slot is set to " { $snippet "val" } "." }
 373 }
 374 $nl
 375 "Thus, instead of"
 376 { $code
 377   "<graph>"
 378   "    <graph-attributes>"
 379   "        \"Bad-ass graph\" >>label"
 380   "    add"
 381   "    1 2 <edge> dup attributes>>"
 382   "        \"This edge is dumb\" swap label<<"
 383   "    add"
 384   "    3 <node> dup attributes>>"
 385   "        \"This node is cool\" swap label<<"
 386   "    add"
 387 }
 388 "you can simply write"
 389 { $code
 390   "<graph>"
 391   "    \"Bad-ass graph\" =label"
 392   "    1 2 <edge>"
 393   "        \"This edge is dumb\" =label"
 394   "    add"
 395   "    3 <node>"
 396   "        \"This node is cool\" =label"
 397   "    add"
 398 }
 399 $nl
 400 "However, since the slot " { $slot "labelloc" } " only exists in " { $link graph-attributes } " and " { $link node-attributes } ", there won't be a method for " { $link edge } " or " { $link edge-attributes } " objects:"
 401 { $example
 402     "USING: continuations graphviz graphviz.notation io kernel ;"
 403     "<graph>"
 404     "    ! This is OK:"
 405     "    \"t\" =labelloc"
 406     ""
 407     "    ! This is not OK:"
 408     "    [ 1 2 <edge> \"b\" =labelloc add ]"
 409     "    [ drop \"not for edges!\" write ] recover drop"
 410     "not for edges!"
 411 }
 412 $nl
 413 "For the full list of attribute-setting words, consult the list of generic words for the " { $vocab-link "graphviz.notation" } " vocabulary."
 414 ;
 415
 416 ARTICLE: { "graphviz.notation" "synonyms" } "Aliases that resemble DOT code"
 417 "The " { $vocab-link "graphviz.notation" } " vocabulary provides aliases for words defined in the " { $vocab-link "graphviz" } " and " { $vocab-link "graphviz.attributes" } " vocabularies. These will make Factor code read more like DOT code (see " { $url "https://graphviz.org/content/dot-language" } ")."
 418 $nl
 419 "Notation for edges without attributes:"
 420 { $subsections
 421     --
 422     ->
 423     ~--
 424     ~->
 425 }
 426 "Notation for nodes/edges with local attributes:"
 427 { $subsections
 428     [add-node
 429     [add-edge
 430     [--
 431     [->
 432 }
 433 "Notation for global attributes:"
 434 { $subsections
 435     [node
 436     [edge
 437     [graph
 438 }
 439 "Word to \"close off\" notation for attributes:"
 440 { $subsections
 441     ];
 442 }
 443 ;
 444
 445 ARTICLE: "graphviz.notation" "Graphviz notation"
 446 "The " { $vocab-link "graphviz.notation" } " vocabulary provides words for building " { $link graph } "s in a way that looks similar to the DOT language (see " { $url "https://graphviz.org/content/dot-language" } ")."
 447 $nl
 448 "The " { $vocab-link "graphviz" } " vocabulary alone already follows the general structure of the DOT language: " { $link graph } "s and " { $link subgraph } "s consist of an ordered sequence of " { $slot "statements" } "; each statement will " { $link add } " either a " { $link node } ", an " { $link edge } ", or some attribute declaration (" { $links graph-attributes node-attributes edge-attributes } "); and " { $slot "attributes" } " may be set on individual " { $link node } "s and " { $link edge } "s. Even some DOT niceties are already supported, like being able to have an " { $link edge } " between anonymous " { $link subgraph } "s. For instance, compare"
 449 { $code
 450   "<digraph>"
 451   "    { 1 2 3 } { 4 5 6 } add-edge"
 452 }
 453 "with the DOT code"
 454 { $code
 455   "digraph {"
 456   "    { 1 2 3 } -> { 4 5 6 }"
 457   "}"
 458 }
 459 $nl
 460 "However, there are some rough points that this vocabulary addresses:"
 461 { $subsections
 462     { "graphviz.notation" "=attrs" }
 463     { "graphviz.notation" "synonyms" }
 464 }
 465 ;
 466
 467 ABOUT: "graphviz.notation"