lsu.h File Reference

Lopsub Utilities, enums and public functions. More...

Enumerations
enum	lsu_merge_cf_flags { MCF_OVERRIDE = 1, MCF_DONT_FREE = 2 }
	Flags for lsu_merge_config_file_options(). More...

Functions
int	lsu_com_help (bool long_help, const struct lls_parse_result *lpr, const struct lls_suite *suite, const char *(*aux_info_cb)(unsigned cmd_num, bool verbose), char **result, unsigned *num_chars)
	A generic implementation of the help subcommand. More...
int	lsu_merge_config_file_options (const char *path, const char *dflt, struct lls_parse_result **lpr, const struct lls_command *cmd, const struct lls_suite *suite, unsigned flags)
	Merge command line options and config file options. More...

Detailed Description

Lopsub Utilities, enums and public functions.

Enumeration Type Documentation

lsu_merge_cf_flags

enum lsu_merge_cf_flags

Flags for lsu_merge_config_file_options().

Enumerator
MCF_OVERRIDE	Whether the options specified in the configuration file should override the currently effective options. At application startup this is usually unset so that command line options take precedence over config file options. However, if the application supports re-reading the configuration, it can make sense to enable this flag.
MCF_DONT_FREE	After the two lopsub parse results have been merged, the merged parse result usually becomes the effective configuration and the parse result which corresponds to the former effective options is no longer needed. Therefore lsu_merge_config_file_options() frees this former parse result by default. This flag instructs the function to keep it. This is mostly useful if the application supports re-reading the config file so that the parse result which corresponds to the command line options is kept for future calls to lsu_merge_config_file_options().

Function Documentation

lsu_com_help()

int lsu_com_help	(	bool	long_help,
		const struct lls_parse_result *	lpr,
		const struct lls_suite *	suite,
		const char *(*)(unsigned cmd_num, bool verbose)	aux_info_cb,
		char **	result,
		unsigned *	num_chars
	)

A generic implementation of the help subcommand.

This function returns the help text for the given subcommand, or the list of all subcommands if no non-option argument is given. The function is generic in that it works for arbitrary lopsub suites.

Parameters

long_help	Applies to both command list and command help.
suite	The supercommand, if any, is omitted.
lpr	Used to determine whether a non-option argument is given.
aux_info_cb	Optional callback, may return NULL, static memory.
result	Must be freed by the caller.
num_chars	Initialized to the length of the returned string, optional.

If the optional aux_info_cb function pointer is not NULL, the callback function must return the string representation of the aux_info structure of the given command, or NULL to indicate that this command has no aux info structure.

The function fails if lpr has more than one non-option argument, or if there is exactly one non-option argument, but this argument is not the name of a subcommand in the given lopsub suite.

Returns

Standard. In the failure case a suitable error message is returned via the result pointer and num_chars is set accordingly.

lsu_merge_config_file_options()

int lsu_merge_config_file_options	(	const char *	path,
		const char *	dflt,
		struct lls_parse_result **	lpr,
		const struct lls_command *	cmd,
		const struct lls_suite *	suite,
		unsigned	flags
	)

Merge command line options and config file options.

This function parses the options stored in the configuration file and merges them with the currently effective options. If the application supports config files, it is supposed to call this after the command line options have been parsed. If the application also supports config file reloading, the function will be called for that purpose.

Parameters

path	Config file path, usually the argument to –config-file.
dflt	Relative to ~/.paraslash, ignored if path is not NULL.
lpr	Value-result pointer.
cmd	Passed to lls_parse() and lls_merge().
suite	Needed to tell whether cmd is the supercommand.
flags	See enum lsu_merge_cf_flags.

The function does nothing if path is NULL and the default config file does not exist, or if path is an empty file. Otherwise, the options of the config file are parsed, the parse result is merged with lpr, and the merged parse result is returned via lpr.

By default, lpr is freed if the merge was done, but this can be changed by including MCF_DONT_FREE flags.

Returns

Zero if there was nothing to do, one if the config file options were merged successfully, negative error code on failure. It is considered an error if path is given, but the file does not exist.