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
     instances that can	appear multiple	times.	A container is used to hold
     related fields and	to give	the data organization and scope.  The con-
     tainer 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
     instances 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	Ports 11.2	       December	4, 2014		    FreeBSD Ports 11.2

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | EMITTING HIERARCHY | DTRT MODE | SEE ALSO | HISTORY | AUTHORS

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

home | help