xo_set_info(3) [freebsd man page]

LIBXO(3)						   BSD Library Functions Manual 						  LIBXO(3)

NAME

     xo_emit -- emit formatted output based on format string and arguments

LIBRARY

     library ``libxo''

SYNOPSIS

     #include <libxo/xo.h>

     void
     xo_set_info(xo_handle_t *handle, xo_info_t *info, int count);

DESCRIPTION

     HTML data can include additional information in attributes that begin with "data-".  To enable this, three things must occur:

     First the application must build an array of xo_info_t structures, one per tag.  The array must be sorted by name, since libxo uses a binary
     search to find the entry that matches names from format instructions.

     The xo_info_t structure is defined in <libxo/xo.h>:

	       typedef struct xo_info_s {
		   const char *xi_name;    /* Name of the element */
		   const char *xi_type;    /* Type of field */
		   const char *xi_help;    /* Description of field */
	       } xo_info_t;

     Second, the application must inform libxo about this information using the xo_set_info() call.  Like other libxo calls, passing NULL for the
     handle tells libxo to use the default handle.

     If the count is -1, libxo will count the elements of info, but there must be an empty element at the end.	More typically, the number is
     known to the application:

	       xo_info_t info[] = {
		   { "in-stock", "number", "Number of items in stock" },
		   { "name", "string", "Name of the item" },
		   { "on-order", "number", "Number of items on order" },
		   { "sku", "string", "Stock Keeping Unit" },
		   { "sold", "number", "Number of items sold" },
	       };
	       int info_count = (sizeof(info) / sizeof(info[0]));
	       ...
	       xo_set_info(NULL, info, info_count);

     Third, the emission of info must be triggered with the XOF_INFO flag using either the xo_set_flags() function or the ``--libxo=info'' command
     line argument.

     The type and help values, if present, are emitted as the "data-type" and "data-help" attributes:

	     <div class="data" data-tag="sku" data-type="string"
		  data-help="Stock Keeping Unit">GRO-000-533</div>

ADDITIONAL DOCUMENTATION

     Complete documentation can be found on github:

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

SEE ALSO

     xo_emit(3)

HISTORY

     The libxo library was added in FreeBSD 11.0.

AUTHOR

     Phil Shafer

BSD
								 December 4, 2014							       BSD

LIBXO(3)						   BSD Library Functions Manual 						  LIBXO(3)

NAME

     xo_emit -- emit formatted output based on format string and arguments

LIBRARY

     library ``libxo''

SYNOPSIS

     #include <libxo/xo.h>
LIBXO(3)						   BSD 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 containers

LIBRARY

     library ``libxo''

SYNOPSIS

     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 to 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
     handle.

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

     Each open call must 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 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 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 containers, lists, and instances.	A warning is generated when the name given
     to the close function and the name recorded do not match.

ADDITIONAL DOCUMENTATION

     Complete documentation can be found on github:

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

SEE ALSO

     xo_emit(3)

HISTORY

     The libxo library was added in FreeBSD 11.0.

AUTHOR

     Phil Shafer

BSD
								 December 4, 2014							       BSD