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

NAME
     xo_open_container,        xo_open_container_h,	   xo_open_container_hd,
     xo_open_container_d	xo_close_container,	   xo_close_container_h,
     xo_close_container_hd,  xo_close_container_d  -- open (and close) container
     constructs

LIBRARY
     libxo

SYNOPSIS
     #include <libxo/xo.h>

     int
     xo_open_container(const char *name);

     int
     xo_open_container_h(xo_handle_t *handle, const char *name);

     int
     xo_open_container_hd(xo_handle_t *handle, const char *name);

     int
     xo_open_container_d(const char *name);

     int
     xo_close_container(const char *name);

     int
     xo_close_container_h(xo_handle_t *handle, const char *name);

     int
     xo_close_container_hd(xo_handle_t *handle);

     int
     xo_close_container_d(void);

DESCRIPTION
     libxo represents two types of hierarchy: "containers" and "lists".  A  con-
     tainer  appears  once  under a given parent where a list contains instances
     that can appear multiple times.  A container is used to hold related fields
     and to give the data organization and scope.  The container has  no  value,
     but serves to contain other nodes.

     To  open  a  container,  call xo_open_container() or xo_open_container_h().
     The former uses the default handle and the latter accepts a  specific  han-
     dle.

     To  close	a  level, use the xo_close_container() or xo_close_container_h()
     functions.

     Each open call should have a matching close call.	If the XOF_WARN flag  is
     set  and  the name given does not match the name of the currently open con-
     tainer, a warning will be generated.
	       Example:

		   xo_open_container("top");
		   xo_open_container("system");
		   xo_emit("{:host-name/%s%s%s", hostname,
			   domainname ? "." : "", domainname ?: "");
		   xo_close_container("system");
		   xo_close_container("top");

	       Sample Output:
		 Text:
		   my-host.example.org
		 XML:
		   <top>
		     <system>
			 <host-name>my-host.example.org</host-name>
		     </system>
		   </top>
		 JSON:
		   "top" : {
		     "system" : {
			 "host-name": "my-host.example.org"
		     }
		   }
		 HTML:
		   <div class="data"
			data-tag="host-name">my-host.example.org</div>

EMITTING HIERARCHY
     To create a container, use the xo_open_container() and xo_close_container()
     set of functions.	The handle parameter contains a handle such as	returned
     by  xo_create(3)  or  NULL  to  use the default handle.  The name parameter
     gives the name of the container, encoded in UTF-8.  Since ASCII is a proper
     subset of UTF-8, traditional C strings can be used directly.

     The close functions with the "_d" suffix are used in "Do The  Right  Thing"
     mode, where the name of the open containers, lists, and instances are main-
     tained  internally  by  libxo to allow the caller to avoid keeping track of
     the open container name.

     Use the XOF_WARN flag to generate a warning if the name given on the  close
     does not match the current open container.

     For  TEXT	and  HTML  output, containers are not rendered into output text,
     though for HTML they are used when the XOF_XPATH flag is set.

	       EXAMPLE:
		  xo_open_container("system");
		  xo_emit("The host name is {:host-name}0, hn);
		  xo_close_container("system");
	       XML:
		  <system><host-name>foo</host-name></system>

DTRT MODE
     Some users may find tracking the names of open containers, lists,	and  in-
     stances  inconvenient.   libxo  offers  a	"Do The Right Thing" mode, where
     libxo will track the names of open containers, lists, and instances so  the
     close  function can be called without a name.  To enable DTRT mode, turn on
     the XOF_DTRT flag prior to making any other libxo output.
	       xo_set_flags(NULL, XOF_DTRT);
     Each open and close function has a version with the suffix "_d", which will
     close the open container, list, or instance:
	       xo_open_container("top");
	       ...
	       xo_close_container_d();
     Note that the XOF_WARN flag will also cause libxo to track open containers,
     lists, and instances.  A warning is generated when the name  given  to  the
     close function and the name recorded do not match.

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	December 4, 2014			LIBXO(3)
home | help