paraslash Paraslash Audio Streaming
About   News   Download   Documentation   Development

Enumerations | Functions
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

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_helpApplies to both command list and command help.
suiteThe supercommand, if any, is omitted.
lprUsed to determine whether a non-option argument is given.
aux_info_cbOptional callback, may return NULL, static memory.
resultMust be freed by the caller.
num_charsInitialized 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
pathConfig file path, usually the argument to –config-file.
dfltRelative to ~/.paraslash, ignored if path is not NULL.
lprValue-result pointer.
cmdPassed to lls_parse() and lls_merge().
suiteNeeded to tell whether cmd is the supercommand.
flagsSee 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.