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

NAME
     xo_open_list,	xo_open_list_h,      xo_open_list_hd,	  xo_open_list_d
     xo_open_instance,	       xo_open_instance_h,	    xo_open_instance_hd,
     xo_open_instance_d 	 xo_close_instance,	    xo_close_instance_h,
     xo_close_instance_hd, xo_close_instance_d	xo_close_list,	xo_close_list_h,
     xo_close_list_hd, xo_close_list_d -- open and close lists and instances

LIBRARY
     libxo

SYNOPSIS
     #include <libxo/xo.h>

     int
     xo_open_list_h(xo_handle_t *xop, const char *name);

     int
     xo_open_list(const char *name);

     int
     xo_open_list_hd(xo_handle_t *xop, const char *name);

     int
     xo_open_list_d(const char *name);

     int
     xo_open_instance_h(xo_handle_t *xop, const char *name);

     int
     xo_open_instance(const char *name);

     int
     xo_open_instance_hd(xo_handle_t *xop, const char *name);

     int
     xo_open_instance_d(const char *name);

     int
     xo_close_instance_h(xo_handle_t *xop, const char *name);

     int
     xo_close_instance(const char *name);

     int
     xo_close_instance_hd(xo_handle_t *xop);

     int
     xo_close_instance_d(void);

     int
     xo_close_list_h(xo_handle_t *xop, const char *name);

     int
     xo_close_list(const char *name);

     int
     xo_close_list_hd(xo_handle_t *xop);

     int
     xo_close_list_d(void);

DESCRIPTION
     Lists are sequences of instances of homogeneous data objects.  Two distinct
     levels  of  calls are needed to represent them in our output styles.  Calls
     must be made to open and close a list, and for each  instance  of	data  in
     that list, calls must be make to open and close that instance.

     The name given to all calls must be identical, and it is strongly suggested
     that  the	name be singular, not plural, as a matter of style and usage ex-
     pectations.

     A list is a set of one or more instances that appear under the same parent.
     The instances contain details about a specific object.  One  can  think  of
     instances	as  objects  or records.  A call is needed to open and close the
     list, while a distinct call is needed to open and close  each  instance  of
     the list:
	       xo_open_list("item");

	       for (ip = list; ip->i_title; ip++) {
		   xo_open_instance("item");
		   xo_emit("{L:Item} '{:name/%s}':0, ip->i_title);
		   xo_close_instance("item");
	       }

	       xo_close_list("item");
     Getting  the list and instance calls correct is critical to the proper gen-
     eration of XML and JSON data.

	       EXAMPLE:
		   xo_open_list("user");
		   for (i = 0; i < num_users; i++) {
		       xo_open_instance("user");
		       xo_emit("{k:name}:{:uid/%u}:{:gid/%u}:{:home}0,
			       pw[i].pw_name, pw[i].pw_uid,
			       pw[i].pw_gid, pw[i].pw_dir);
		       xo_close_instance("user");
		   }
		   xo_close_list("user");
	       TEXT:
		   phil:1001:1001:/home/phil
		   pallavi:1002:1002:/home/pallavi
	       XML:
		   <user>
		       <name>phil</name>
		       <uid>1001</uid>
		       <gid>1001</gid>
		       <home>/home/phil</home>
		   </user>
		   <user>
		       <name>pallavi</name>
		       <uid>1002</uid>
		       <gid>1002</gid>
		       <home>/home/pallavi</home>
		   </user>
	       JSON:
		   user: [
		       {
			   "name": "phil",
			   "uid": 1001,
			   "gid": 1001,
			   "home": "/home/phil",
		       },
		       {
			   "name": "pallavi",
			   "uid": 1002,
			   "gid": 1002,
			   "home": "/home/pallavi",
		       }
		   ]

LEAF LISTS
     In contrast to a list of instances, a "leaf list" is list of simple values.
     To emit a leaf list, call the xo_emit() function using the ""l"" modifier:
	       for (ip = list; ip->i_title; ip++) {
		   xo_emit("{Lwc:Item}{l:item}0, ip->i_title);
	       }

     The name of the field must match the name of the leaf list.

     In JSON, leaf lists are rendered as arrays of values.   In  XML,  they  are
     rendered as multiple leaf elements.
	       JSON:
		   "item": "hammer", "nail"
	       XML:
		   <item>hammer</item>
		   <item>nail</item>

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