2 .\" # Copyright (c) 2015, Juniper Networks, Inc.
3 .\" # All rights reserved.
4 .\" # This SOFTWARE is licensed under the LICENSE provided in the
5 .\" # ../Copyright file. By downloading, installing, copying, or
6 .\" # using the SOFTWARE, you agree to be bound by the terms of that
8 .\" # Phil Shafer, January 2015
15 .Nd prevent and allow closing of open constructs
25 .Nd open and close markers
30 .Fn xo_open_marker "const char *name"
32 .Fn xo_open_marker_h "xo_handle_t *handle" "const char *name"
34 .Fn xo_close_marker "const char *name"
36 .Fn xo_close_marker_h "xo_handle_t *handle" "const char *name"
39 represents hierarchy using two constructs:
43 A marker can be used to affect how open constructs are closed, either
44 by preventing their (implicit or explicit) closure or by forcing their
46 While a marker is open, no other open constructs can be closed.
47 When a marker is closed, all constructs open since the marker was opened
49 A marker is used to "freeze" any open constructs.
52 functions that would normally close them will be ignored, effectively
53 blocking their closure.
56 is called, any containers, lists, or leaf-lists open since the
59 call will be close and the marker discarded.
60 Markers use names which are not user-visible, allowing the caller to
61 choose appropriate internal names.
62 The marker has no value and is not emitted in any form.
64 To open a marker, call
67 .Fn xo_open_marker_h .
68 The former uses the default handle and
69 the latter accepts a specific handle.
71 To close a marker, use the
77 Each open call must have a matching close call.
80 .Fn xo_close_container
81 call on line [1] will be ignored, since the open marker "outer"
82 will prevent close of any open constructs that precede it.
85 call on line [2] will close the "system" container, since it was
86 opened after the "outer" marker.
87 .Bd -literal -offset indent -compact
90 xo_open_container("top");
91 xo_open_marker("outer");
92 xo_open_container("system");
93 xo_emit("{:host-name/%s%s%s", hostname,
94 domainname ? "." : "", domainname ?: "");
95 xo_close_container("top"); /* [1] */
96 xo_close_marker("outer"); /* [2] */
97 xo_close_container("top");
100 In this example, the code whiffles through a list of fish, calling a
101 function to emit details about each fish. The marker "fish-guts" is
102 used to ensure that any constructs opened by the function are closed
104 .Bd -literal -offset indent
105 for (i = 0; fish[i]; i++) {
106 xo_open_instance("fish");
107 xo_open_marker("fish-guts");
108 dump_fish_details(i);
109 xo_close_marker("fish-guts");
112 .Sh ADDITIONAL DOCUMENTATION
113 Complete documentation can be found on github:
114 .Bd -literal -offset indent
115 http://juniper.github.io/libxo/libxo-manual.html
120 .Bd -literal -offset indent
121 https://github.com/Juniper/libxo
124 The latest release of
127 .Bd -literal -offset indent
128 https://github.com/Juniper/libxo/releases