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
14 .Nm xo_open_marker , xo_open_marker_h , xo_close_marker , xo_close_marker_h
15 .Nd prevent and allow closing of open constructs
21 .Fn xo_open_marker "const char *name"
23 .Fn xo_open_marker_h "xo_handle_t *handle" "const char *name"
25 .Fn xo_close_marker "const char *name"
27 .Fn xo_close_marker_h "xo_handle_t *handle" "const char *name"
30 represents hierarchy using two constructs:
34 A marker can be used to affect how open constructs are closed, either
35 by preventing their (implicit or explicit) closure or by forcing their
37 While a marker is open, no other open constructs can be closed.
38 When a marker is closed, all constructs open since the marker was opened
40 A marker is used to "freeze" any open constructs.
43 functions that would normally close them will be ignored, effectively
44 blocking their closure.
47 is called, any containers, lists, or leaf-lists open since the
50 call will be close and the marker discarded.
51 Markers use names which are not user-visible, allowing the caller to
52 choose appropriate internal names.
53 The marker has no value and is not emitted in any form.
55 To open a marker, call
58 .Fn xo_open_marker_h .
59 The former uses the default handle and
60 the latter accepts a specific handle.
62 To close a marker, use the
68 Each open call must have a matching close call.
71 .Fn xo_close_container
72 call on line [1] will be ignored, since the open marker "outer"
73 will prevent close of any open constructs that precede it.
76 call on line [2] will close the "system" container, since it was
77 opened after the "outer" marker.
78 .Bd -literal -offset indent -compact
81 xo_open_container("top");
82 xo_open_marker("outer");
83 xo_open_container("system");
84 xo_emit("{:host-name/%s%s%s", hostname,
85 domainname ? "." : "", domainname ?: "");
86 xo_close_container("top"); /* [1] */
87 xo_close_marker("outer"); /* [2] */
88 xo_close_container("top");
91 In this example, the code whiffles through a list of fish, calling a
92 function to emit details about each fish. The marker "fish-guts" is
93 used to ensure that any constructs opened by the function are closed
95 .Bd -literal -offset indent
96 for (i = 0; fish[i]; i++) {
97 xo_open_instance("fish");
98 xo_open_marker("fish-guts");
100 xo_close_marker("fish-guts");
109 library first appeared in
114 .An Phil Shafer Aq Mt phil@freebsd.org .