LIBXO(3) BSD Library Functions Manual LIBXO(3)NAMExo_open_marker — prevent and allow closing of open constructs
LIBRARY
library “libxo”
SYNOPSIS
#include <libxo/xo.h>
LIBXO(3) BSD Library Functions Manual LIBXO(3)NAMExo_open_marker
xo_open_marker_h
xo_close_marker
xo_close_marker_h — open and close markers
LIBRARY
library “libxo”
SYNOPSIS
int
xo_open_marker(const char *name);
int
xo_open_marker_h(xo_handle_t *handle, const char *name);
int
xo_close_marker(const char *name);
int
xo_close_marker_h(xo_handle_t *handle, const char *name);
DESCRIPTION
libxo represents hierarchy using two constructs: “containers” and
“lists”. A marker can be used to affect how open constructs are closed,
either by preventing their (implicit or explicit) closure or by forcing
their closure. While a marker is open, no other open constructs can be
closed. When a marker is closed, all constructs open since the marker
was opened will be closed. A marker is used to "freeze" any open con‐
structs. Calls to xo_close_*() functions that would normally close them
will be ignored, effectively blocking their closure. However when
xo_close_marker() is called, any containers, lists, or leaf-lists open
since the matching xo_open_marker() call will be close and the marker
discarded. Markers use names which are not user-visible, allowing the
caller to choose appropriate internal names. The marker has no value and
is not emitted in any form.
To open a marker, call xo_open_marker() or xo_open_marker_h(). The for‐
mer uses the default handle and the latter accepts a specific handle.
To close a marker, use the xo_close_marker() or xo_close_marker_h() func‐
tions.
Each open call must have a matching close call.
In this example, the xo_close_container() call on line [1] will be
ignored, since the open marker "outer" will prevent close of any open
constructs that precede it. The xo_close_marker() call on line [2] will
close the "system" container, since it was opened after the "outer"
marker.
Example:
xo_open_container("top");
xo_open_marker("outer");
xo_open_container("system");
xo_emit("{:host-name/%s%s%s", hostname,
domainname ? "." : "", domainname ?: "");
xo_close_container("top"); /* [1] */
xo_close_marker("outer"); /* [2] */
xo_close_container("top");
In this example, the code whiffles through a list of fish, calling a
function to emit details about each fish. The marker "fish-guts" is used
to ensure that any constructs opened by the function are closed properly.
for (i = 0; fish[i]; i++) {
xo_open_instance("fish");
xo_open_marker("fish-guts");
dump_fish_details(i);
xo_close_marker("fish-guts");
}
ADDITIONAL DOCUMENTATION
Complete documentation can be found on github:
http://juniper.github.io/libxo/libxo-manual.html
libxo lives on github as:
https://github.com/Juniper/libxo
The latest release of libxo is available at:
https://github.com/Juniper/libxo/releases
SEE ALSOxo_emit(3)HISTORY
The libxo library was added in FreeBSD 11.0.
AUTHOR
Phil Shafer
BSD January 22, 2015 BSD
