go-vise

Constrained Size Output Virtual Machine
Info | Log | Files | Refs | README | LICENSE

navigation.texi (2620B)

      1 @node navigation
      2 @chapter Navigation
      3 
      4 
      5 Nodes are navigated by name, using a navigation stack.
      6 
      7 Every movement @emph{down} adds a node to the stack, and every movement @emph{up} removes one node from the stack.
      8 
      9 Additionally, @emph{lateral} movement is available, for nodes whose contents span mulitple pages.
     10 
     11 
     12 @section Entry point
     13 
     14 All VM executions require an @emph{entry point}.
     15 
     16 If not explicitly set in the code, the node name @code{root} is used.
     17 
     18 Attempting to navigate @emph{up} from the entry point node will fail and terminate execution.
     19 
     20 
     21 @anchor{lateral_navigation}
     22 @section Lateral navigation
     23 
     24 Lateral navigation is only available for node output spanning multiple pages. See @ref{render_multi, Multi-page rendering} for details.
     25 
     26 Lateral navigation will fail and terminate execution when:
     27 
     28 @itemize
     29 @item executing a single-page node.
     30 @item attempting @emph{next} beyond the last page.
     31 @item attempting @emph{previous} on the first page.
     32 @end itemize
     33 
     34 
     35 @anchor{node_names}
     36 @section Node names
     37 
     38 Regular node names @emph{must} start with an alphabetical character. The rest of the string may contain alphanumeric characters and underscore.
     39 
     40 @subsection Special node names
     41 
     42 A selection of special node names are available for relative navigation. They are single-character tokens, listed below with their respective ASCII codes.
     43 
     44 @table @code
     45 @item . (0x2E)
     46 Repeat the same node.
     47 @item _ (0x5F)
     48 Go to the previous node in the stack.
     49 @item > (0x3E)
     50 Go to the next page of a multi-page node. Will fail if used in a single-page context and/or resulting page index is out of bounds.
     51 @item < (0x3C)
     52 Go to the next page of a multi-page node. Will fail if used on the first (or single) page.
     53 @item ^ (0x5E)
     54 Go to the topmost node. Will execute each intermediate node in the stack.
     55 @end table
     56 
     57 
     58 @subsection Builtin node names
     59 
     60 Uncaught exceptions in the code flow that should not halt execution are routed to a builtin node named @code{_catch}.
     61 
     62 
     63 @section Navigation stack
     64 
     65 Consider the following navigation example, illustrating the state of the stack for each step after execution.
     66 
     67 @multitable @columnfractions .25 .65 .10
     68 @headitem instruction
     69 @tab stack
     70 @tab page index
     71 @item @code{MOVE foo}
     72 @tab foo
     73 @tab 0
     74 @item @code{MOVE bar}
     75 @tab foo/bar
     76 @tab 0
     77 @item @code{MOVE baz}
     78 @tab foo/bar/baz
     79 @tab 0
     80 @item @code{MOVE >}
     81 @tab foo/bar/baz
     82 @tab 1
     83 @item @code{MOVE >}
     84 @tab foo/bar/baz
     85 @tab 2
     86 @item @code{MOVE <}
     87 @tab foo/bar/baz
     88 @tab 1
     89 @item @code{MOVE .}
     90 @tab foo/bar/baz
     91 @tab 1
     92 @item @code{MOVE _}
     93 @tab foo/bar
     94 @tab 0
     95 @item @code{MOVE baz}
     96 @tab foo/bar/baz
     97 @tab 0
     98 @item @code{MOVE ^}
     99 @tab foo
    100 @tab 0
    101 @end multitable
    102 
    103