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

FreeBSD Manual Pages

  
 
  

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) con-
       tainer 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
       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
       handle.

       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  in-
       stances 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  in-
       stances	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  con-
       tainers,	 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.0	       December	4, 2014			      LIBXO(3)

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+Ports+15.0>

home | help