#ifndef HA_SEXP_H
#define HA_SEXP_H

/**
 * Prints an s-expression to stdout. The spec string is a list of format
 * specifiers describing the structure of the s-expression. Unlike the stdio
 * family of printing functions, % is not used - each character is interpreted
 * directly and there is no means provided for emitting additional unstructured
 * text. The value of each specifier is provided in the remaining arguments.
 * The following format specifiers are used:
 *
 * a: atom (string: alphanumeric, plus _ and -, no spaces)
 * s: string
 * d: integer
 * f: floating point number
 * (, ): list
 * ' ', '\n', '\t': copied to output
 *
 * The return value is the number of bytes written.
 *
 * To write a variable-length list, omit the closing ) from the format string,
 * then call printf several times to write each member. Finish with a final ).
 */
int ha_sexp_printf(const char *spec, ...);

/**
 * Scans an s-expression from stdin which matches the given format specifier,
 * and populates the remaining arguments with the values found in the
 * s-expression. The same format specifiers as ha_sexp_printf are supported, but
 * with the following constraints:
 *
 * a, s: pass one char * argument and one size_t argument with the buffer
 * length. If the buffer length is exceeded, errno is set to ENOBUFS.
 *
 * A, S: pass one char ** argument, which must be initialized to NULL. The
 * buffer will be allocated. ENOMEM may be returned if the buffer cannot be
 * allocated. In the case of an error, your pointer will remain NULL and does
 * not need to be freed.
 *
 * In the case of invalid strings or atoms, errno is set to EINVAL.
 *
 * The return value is the number of values successfully scanned in. This
 * number includes ( and ), but does not include whitespace characters. The
 * caller SHOULD check that this number meets their expectations and should
 * treat this as an error if not.
 *
 * To scan a variable-length list, include the closing ) in your format string.
 * If the return value is equal to the number of values -1, there are additional
 * members to scan. Scan each of these additional members without the opening (,
 * but include the closing ). Continue scanning until the ) is included in the
 * number of successfully scanned values.
 */
int ha_sexp_scanf(const char *spec, ...);

#endif