home | help 
LIBXO(3)		     Library Functions Manual			LIBXO(3)

NAME
     xo_open_marker,  xo_open_marker_h,  xo_close_marker,  xo_close_marker_h  --
     prevent and allow closing of open constructs

LIBRARY
     libxo

SYNOPSIS
     #include <libxo/xo.h>

     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  clo-
     sure.   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 constructs.  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  former
     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  func-
     tion  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");
	       }

SEE ALSO
     xo_emit(3), libxo(3)

ADDITIONAL DOCUMENTATION
     FreeBSD uses libxo version 0.6.1.	Complete documentation can be  found  on
     github:

	   http://juniper.github.io/libxo/0.6.1/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

HISTORY
     The libxo library was added in FreeBSD 11.0.

AUTHOR
     Phil Shafer

FreeBSD ports 15.quarterly	January 22, 2015			LIBXO(3)
home | help