Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
LIBXO(3)	       FreeBSD 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
     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
     container appears once under a given parent where a list contains in-
     stances that can appear multiple times.  A	container is used to hold re-
     lated 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
     container,	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	han-
     dle.  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
     maintained	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 contain-
     ers, 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)

HISTORY
     The libxo library first appeared in FreeBSD 11.0.

AUTHORS
     libxo was written by Phil Shafer <phil@freebsd.org>.

FreeBSD	13.0		       December	4, 2014			  FreeBSD 13.0
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | EMITTING HIERARCHY | DTRT MODE | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=xo_open_container&sektion=3&manpath=FreeBSD+12.0-RELEASE>

home | help