1.\" #
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
7.\" # LICENSE.
8.\" # Phil Shafer, January 2015
9.\"
10.Dd January 22, 2015
11.Dt LIBXO 3
12.Os
13.Sh NAME
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
16.Sh LIBRARY
17.Lb libxo
18.Sh SYNOPSIS
19.In libxo/xo.h
20.Ft xo_ssize_t
21.Fn xo_open_marker "const char *name"
22.Ft xo_ssize_t
23.Fn xo_open_marker_h "xo_handle_t *handle" "const char *name"
24.Ft xo_ssize_t
25.Fn xo_close_marker "const char *name"
26.Ft xo_ssize_t
27.Fn  xo_close_marker_h "xo_handle_t *handle" "const char *name"
28.Sh DESCRIPTION
29.Nm libxo
30represents hierarchy using two constructs:
31.Dq containers
32and
33.Dq lists .
34A marker can be used to affect how open constructs are closed, either
35by preventing their (implicit or explicit) closure or by forcing their
36closure.
37While a marker is open, no other open constructs can be closed.
38When a marker is closed, all constructs open since the marker was opened
39will be closed.
40A marker is used to "freeze" any open constructs.
41Calls to
42.Fn xo_close_*
43functions that would normally close them will be ignored, effectively
44blocking their closure.
45However when
46.Fn xo_close_marker
47is called, any containers, lists, or leaf-lists open since the
48matching
49.Fn xo_open_marker
50call will be close and the marker discarded.
51Markers use names which are not user-visible, allowing the caller to
52choose appropriate internal names.
53The marker has no value and is not emitted in any form.
54.Pp
55To open a marker, call
56.Fn xo_open_marker
57or
58.Fn xo_open_marker_h .
59The former uses the default handle and
60the latter accepts a specific handle.
61.Pp
62To close a marker, use the
63.Fn xo_close_marker
64or
65.Fn xo_close_marker_h
66functions.
67.Pp
68Each open call must have a matching close call.
69.Pp
70In this example, the
71.Fn xo_close_container
72call on line [1] will be ignored, since the open marker "outer"
73will prevent close of any open constructs that precede it.
74The
75.Fn xo_close_marker
76call on line [2] will close the "system" container, since it was
77opened after the "outer" marker.
78.Bd -literal -offset indent -compact
79    Example:
80
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");
89.Ed
90.Pp
91In this example, the code whiffles through a list of fish, calling a
92function to emit details about each fish.  The marker "fish-guts" is
93used to ensure that any constructs opened by the function are closed
94properly.
95.Bd -literal -offset indent
96    for (i = 0; fish[i]; i++) {
97        xo_open_instance("fish");
98        xo_open_marker("fish-guts");
99        dump_fish_details(i);
100        xo_close_marker("fish-guts");
101    }
102.Ed
103.Sh SEE ALSO
104.Xr xo_emit 3 ,
105.Xr libxo 3
106.Sh HISTORY
107The
108.Nm libxo
109library first appeared in
110.Fx 11.0 .
111.Sh AUTHORS
112.Nm libxo
113was written by
114.An Phil Shafer Aq Mt phil@freebsd.org .
115
116