clap.h File Reference

Main public API for libclap. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdio.h>
#include <clap/clap_version.h>
#include <clap/clap_error.h>
#include <clap/clap_types.h>
#include <clap/clap_action.h>
#include <clap/clap_allocator.h>
#include <clap/clap_export.h>

Include dependency graph for clap.h:

Go to the source code of this file.

Macros
#define	CLAP_NARGS_ZERO_OR_ONE   (-3)
#define	CLAP_NARGS_ZERO_OR_MORE   (-4)
#define	CLAP_NARGS_ONE_OR_MORE   (-5)
#define	CLAP_NARGS_OPTIONAL   CLAP_NARGS_ZERO_OR_ONE
#define	CLAP_NARGS_REMAINDER   (-1)

Functions
CLAP_EXPORT clap_parser_t *	clap_parser_new (const char *prog_name, const char *description, const char *epilog)
	Create a new argument parser.
CLAP_EXPORT void	clap_parser_free (clap_parser_t *parser)
	Destroy a parser and all resources it owns.
CLAP_EXPORT void	clap_parser_set_help_width (clap_parser_t *parser, int width)
	Set help output width (default: 100).
CLAP_EXPORT void	clap_parser_set_allow_abbrev (clap_parser_t *parser, bool allow)
	Enable or disable abbreviated option matching.
CLAP_EXPORT void	clap_parser_set_version (clap_parser_t *parser, const char *version)
	Set the version string printed by clap_print_version().
CLAP_EXPORT clap_argument_t *	clap_add_argument (clap_parser_t *parser, const char *name_or_flags)
	Register a new argument (positional or optional).
CLAP_EXPORT clap_argument_t *	clap_argument_help (clap_argument_t *arg, const char *help_text)
	Set the help text for an argument.
CLAP_EXPORT clap_argument_t *	clap_argument_type (clap_argument_t *arg, const char *type_name)
	Set the type name for an argument.
CLAP_EXPORT clap_argument_t *	clap_argument_default (clap_argument_t *arg, const char *default_value)
	Set a default value for an argument.
CLAP_EXPORT clap_argument_t *	clap_argument_required (clap_argument_t *arg, bool required)
	Mark an optional argument as required or not.
CLAP_EXPORT clap_argument_t *	clap_argument_choices (clap_argument_t *arg, const char **choices, size_t count)
	Restrict an argument to a fixed set of choices.
CLAP_EXPORT clap_argument_t *	clap_argument_nargs (clap_argument_t *arg, int nargs)
	Set the number of values consumed by this argument.
CLAP_EXPORT clap_argument_t *	clap_argument_action (clap_argument_t *arg, clap_action_t action)
	Set the action type for an argument.
CLAP_EXPORT clap_argument_t *	clap_argument_metavar (clap_argument_t *arg, const char *metavar)
	Override the metavar shown in help/usage for this argument.
CLAP_EXPORT clap_argument_t *	clap_argument_dest (clap_argument_t *arg, const char *dest)
	Override the destination key (dest) in the namespace.
CLAP_EXPORT clap_argument_t *	clap_argument_const (clap_argument_t *arg, const char *const_value)
	Set the constant value for STORE_CONST / APPEND_CONST actions.
CLAP_EXPORT clap_argument_t *	clap_argument_handler (clap_argument_t *arg, clap_action_handler_t handler)
	Register a custom action handler for CLAP_ACTION_CUSTOM.
CLAP_EXPORT clap_argument_t *	clap_argument_data (clap_argument_t *arg, void *data)
	Set user data pointer for a CLAP_ACTION_CUSTOM argument.
CLAP_EXPORT int	clap_add_mutually_exclusive_group (clap_parser_t *parser, bool required)
	Create a mutually exclusive group.
CLAP_EXPORT bool	clap_mutex_group_add_argument (clap_parser_t *parser, int mutex_group_id, clap_argument_t *arg)
	Add an argument to a mutually exclusive group.
CLAP_EXPORT int	clap_add_argument_group (clap_parser_t *parser, const char *title, const char *description)
	Create a display group to organize arguments in help output.
CLAP_EXPORT bool	clap_argument_group_add_argument (clap_parser_t *parser, int display_group_id, clap_argument_t *arg)
	Add an argument to a display group.
CLAP_EXPORT clap_parser_t *	clap_add_subparsers (clap_parser_t *parser, const char *dest, const char *help_text)
	Enable subcommand support.
CLAP_EXPORT clap_parser_t *	clap_subparser_add (clap_parser_t *subparsers, const char *name, const char *help_text)
	Register a subcommand.
CLAP_EXPORT void	clap_subparsers_metavar (clap_parser_t *parser, const char *metavar)
	Override the metavar shown for subcommands in the usage line.
CLAP_EXPORT bool	clap_print_subcommand_help (clap_parser_t *parser, const char *command_name, FILE *stream)
	Print help for a specific subcommand to a stream.
CLAP_EXPORT void	clap_print_help_on_error (clap_parser_t *parser, const clap_error_t *error, FILE *stream)
	Print "<prog>: error: <message>" and contextual help.
CLAP_EXPORT clap_parse_result_t	clap_parse_args (clap_parser_t *parser, int argc, char *argv[], clap_namespace_t **out_namespace, clap_error_t *error)
	Parse command-line arguments.
CLAP_EXPORT void	clap_namespace_free (clap_namespace_t *ns)
	Free a namespace and all values it contains. NULL-safe.
CLAP_EXPORT bool	clap_namespace_get_string (clap_namespace_t *ns, const char *name, const char **value)
	Retrieve a string value from the namespace.
CLAP_EXPORT bool	clap_namespace_get_int (clap_namespace_t *ns, const char *name, int *value)
	Retrieve an int value from the namespace.
CLAP_EXPORT bool	clap_namespace_get_float (clap_namespace_t *ns, const char *name, double *value)
	Retrieve a float value from the namespace.
CLAP_EXPORT bool	clap_namespace_get_bool (clap_namespace_t *ns, const char *name, bool *value)
	Retrieve a bool value from the namespace.
CLAP_EXPORT bool	clap_namespace_get_string_array (clap_namespace_t *ns, const char *name, const char ***values, size_t *count)
	Retrieve a string array from the namespace (APPEND action).
CLAP_EXPORT bool	clap_namespace_set_string (clap_namespace_t *ns, const char *name, const char *value)
	Set a string value in the namespace.
CLAP_EXPORT bool	clap_namespace_set_int (clap_namespace_t *ns, const char *name, int value)
	Set an int value in the namespace.
CLAP_EXPORT bool	clap_namespace_set_float (clap_namespace_t *ns, const char *name, double value)
	Set a float value in the namespace.
CLAP_EXPORT bool	clap_namespace_set_bool (clap_namespace_t *ns, const char *name, bool value)
	Set a bool value in the namespace.
CLAP_EXPORT bool	clap_namespace_append_string (clap_namespace_t *ns, const char *name, const char *value)
	Append a string to an array value in the namespace. Creates the array if the key does not exist yet.
CLAP_EXPORT bool	clap_namespace_has (clap_namespace_t *ns, const char *name)
	Check if a key exists in the namespace.
CLAP_EXPORT void	clap_print_help (clap_parser_t *parser, FILE *stream)
	Print the full help text (usage + all sections) to a stream.
CLAP_EXPORT void	clap_print_version (clap_parser_t *parser, FILE *stream)
	Print "progname version X.Y.Z" to a stream.
CLAP_EXPORT bool	clap_register_type (clap_parser_t *parser, const char *type_name, clap_type_handler_t handler, size_t output_size)
	Register a custom type validator/converter.
CLAP_EXPORT bool	clap_argument_requires (clap_argument_t *arg, clap_argument_t *required_arg, const char *error_msg)
	Declare that arg requires required_arg to also be present.
CLAP_EXPORT bool	clap_argument_conflicts (clap_argument_t *arg, clap_argument_t *conflicting_arg, const char *error_msg)
	Declare that arg and conflicting_arg cannot both appear.

Detailed Description

Main public API for libclap.

libclap is a modern, secure, and extensible command-line argument parsing library for C, inspired by Python's argparse.

Macro Definition Documentation

CLAP_NARGS_ONE_OR_MORE

#define CLAP_NARGS_ONE_OR_MORE   (-5)

'+' - 1 or more arguments

CLAP_NARGS_OPTIONAL

#define CLAP_NARGS_OPTIONAL   CLAP_NARGS_ZERO_OR_ONE

CLAP_NARGS_REMAINDER

#define CLAP_NARGS_REMAINDER   (-1)

Consume all remaining arguments

CLAP_NARGS_ZERO_OR_MORE

#define CLAP_NARGS_ZERO_OR_MORE   (-4)

'*' - 0 or more arguments

CLAP_NARGS_ZERO_OR_ONE

#define CLAP_NARGS_ZERO_OR_ONE   (-3)

'?' - 0 or 1 argument

Function Documentation

clap_add_argument()

CLAP_EXPORT clap_argument_t * clap_add_argument	(	clap_parser_t *	parser,
		const char *	name_or_flags
	)

Register a new argument (positional or optional).

For positional args, pass a bare name: "filename" For optional args, use "--long/-s" syntax (split on '/'):

• "--output/-o" creates both –output and -o
• "--verbose" creates only –verbose

The destination key (dest) is auto-derived from the longest flag: leading dashes stripped, internal dashes replaced with underscores. Override with clap_argument_dest().

Parameters

parser	Target parser.
name_or_flags	Argument spec (see description).

Returns

The new argument on success, NULL on failure (allocation or invalid spec). Configure via clap_argument_* setters.

clap_add_argument_group()

CLAP_EXPORT int clap_add_argument_group	(	clap_parser_t *	parser,
		const char *	title,
		const char *	description
	)

Create a display group to organize arguments in help output.

Arguments in a display group are excluded from the default "Optional arguments" / "Positional arguments" sections and shown under a named group section instead.

Parameters

parser	Target parser.
title	Section title shown in help output.
description	Optional description shown below the title. May be NULL.

Returns

Group ID (positive integer) on success, -1 on failure.

clap_add_mutually_exclusive_group()

CLAP_EXPORT int clap_add_mutually_exclusive_group	(	clap_parser_t *	parser,
		bool	required
	)

Create a mutually exclusive group.

Arguments added to this group via clap_mutex_group_add_argument() cannot appear together on the command line.

Parameters

parser	Target parser.
required	If true, exactly one argument from the group must be provided.

Returns

Group ID (positive integer) on success, -1 on failure. Pass the ID to clap_mutex_group_add_argument().

clap_add_subparsers()

CLAP_EXPORT clap_parser_t * clap_add_subparsers	(	clap_parser_t *	parser,
		const char *	dest,
		const char *	help_text
	)

Enable subcommand support.

After calling this, use clap_subparser_add() to register individual subcommands. Each subcommand is itself a clap_parser_t that can have its own arguments.

Parameters

parser	Target parser.
dest	Namespace key where the matched subcommand name will be stored.
help_text	Description shown in the "Commands:" section of the parent help output. May be NULL.

Returns

A container parser. Pass this to clap_subparser_add(). Returns NULL on failure.

clap_argument_action()

CLAP_EXPORT clap_argument_t * clap_argument_action	(	clap_argument_t *	arg,
		clap_action_t	action
	)

Set the action type for an argument.

Parameters

arg	Target argument.
action	Action type from clap_action_t. Default: STORE.

Returns

arg for chaining.

clap_argument_choices()

CLAP_EXPORT clap_argument_t * clap_argument_choices	(	clap_argument_t *	arg,
		const char **	choices,
		size_t	count
	)

Restrict an argument to a fixed set of choices.

Parameters

arg	Target argument.
choices	Array of NUL-terminated choice strings. The array content is copied internally.
count	Number of elements in choices.

Returns

arg for chaining.

clap_argument_conflicts()

CLAP_EXPORT bool clap_argument_conflicts	(	clap_argument_t *	arg,
		clap_argument_t *	conflicting_arg,
		const char *	error_msg
	)

Declare that arg and conflicting_arg cannot both appear.

If both are provided, parsing fails with CLAP_ERR_DEPENDENCY_VIOLATION and error_msg.

Parameters

arg	Source argument.
conflicting_arg	Argument that conflicts with arg.
error_msg	Error message shown on violation. Copied internally.

Returns

true on success, false on allocation failure.

clap_argument_const()

CLAP_EXPORT clap_argument_t * clap_argument_const	(	clap_argument_t *	arg,
		const char *	const_value
	)

Set the constant value for STORE_CONST / APPEND_CONST actions.

Parameters

arg	Target argument.
const_value	Constant string stored when this argument appears.

Returns

arg for chaining.

clap_argument_data()

CLAP_EXPORT clap_argument_t * clap_argument_data	(	clap_argument_t *	arg,
		void *	data
	)

Set user data pointer for a CLAP_ACTION_CUSTOM argument.

The pointer is passed as the user_data argument to the handler registered with clap_argument_handler(). May be NULL to clear.

Parameters

arg	Target argument with action=CLAP_ACTION_CUSTOM.
data	Opaque pointer passed to the handler. Not copied or freed.

Returns

arg for chaining.

Example

struct config { int limit; };
static bool my_handler(..., void *user_data, ...) {
    struct config *cfg = (struct config *)user_data;
    // use cfg->limit ...
}
 
struct config cfg = { .limit = 100 };
clap_argument_handler(arg, my_handler);
clap_argument_data(arg, &cfg);

clap_argument_default()

CLAP_EXPORT clap_argument_t * clap_argument_default	(	clap_argument_t *	arg,
		const char *	default_value
	)

Set a default value for an argument.

The value is stored as a string and converted to the argument's type when clap_apply_defaults() runs during clap_parse_args().

Parameters

arg	Target argument.
default_value	Default value string, or NULL to clear.

Returns

arg for chaining.

clap_argument_dest()

CLAP_EXPORT clap_argument_t * clap_argument_dest	(	clap_argument_t *	arg,
		const char *	dest
	)

Override the destination key (dest) in the namespace.

By default dest is derived from the longest flag: dashes stripped and internal dashes replaced with underscores.

Parameters

arg	Target argument.
dest	Destination key under which parsed values are stored.

Returns

arg for chaining.

clap_argument_group_add_argument()

CLAP_EXPORT bool clap_argument_group_add_argument	(	clap_parser_t *	parser,
		int	display_group_id,
		clap_argument_t *	arg
	)

Add an argument to a display group.

Parameters

parser	Target parser.
display_group_id	Group ID from clap_add_argument_group().
arg	Argument to assign to the group.

Returns

true on success, false if display_group_id is invalid.

clap_argument_handler()

CLAP_EXPORT clap_argument_t * clap_argument_handler	(	clap_argument_t *	arg,
		clap_action_handler_t	handler
	)

Register a custom action handler for CLAP_ACTION_CUSTOM.

Parameters

arg	Target argument with action=CLAP_ACTION_CUSTOM.
handler	Function pointer invoked when the argument is parsed.

Returns

arg for chaining.

clap_argument_help()

CLAP_EXPORT clap_argument_t * clap_argument_help	(	clap_argument_t *	arg,
		const char *	help_text
	)

Set the help text for an argument.

Parameters

arg	Target argument.
help_text	Help string shown in –help output. May be NULL to clear.

Returns

arg for chaining.

clap_argument_metavar()

CLAP_EXPORT clap_argument_t * clap_argument_metavar	(	clap_argument_t *	arg,
		const char *	metavar
	)

Override the metavar shown in help/usage for this argument.

Parameters

arg	Target argument.
metavar	Metavar string (e.g. "FILE"). May be NULL to reset.

Returns

arg for chaining.

clap_argument_nargs()

CLAP_EXPORT clap_argument_t * clap_argument_nargs	(	clap_argument_t *	arg,
		int	nargs
	)

Set the number of values consumed by this argument.

Use one of the CLAP_NARGS_* constants or a positive integer N. Character literals '?', '+', '*' are also accepted.

Parameters

arg	Target argument.
nargs	Number of values. Use CLAP_NARGS_* constants or a positive integer. Character literals '?', '+', '*' are also accepted. Default: 1.

Returns

arg for chaining.

clap_argument_required()

CLAP_EXPORT clap_argument_t * clap_argument_required	(	clap_argument_t *	arg,
		bool	required
	)

Mark an optional argument as required or not.

Positional arguments ignore this call — they are always required unless their nargs is '?', '*', or REMAINDER.

Parameters

arg	Target argument.
required	true to require, false to make optional.

Returns

arg for chaining.

clap_argument_requires()

CLAP_EXPORT bool clap_argument_requires	(	clap_argument_t *	arg,
		clap_argument_t *	required_arg,
		const char *	error_msg
	)

Declare that arg requires required_arg to also be present.

If arg is provided but required_arg is not, parsing fails with CLAP_ERR_DEPENDENCY_VIOLATION and error_msg.

Parameters

arg	Source argument.
required_arg	Argument that must also be present.
error_msg	Error message shown on violation. Copied internally.

Returns

true on success, false on allocation failure.

clap_argument_type()

CLAP_EXPORT clap_argument_t * clap_argument_type	(	clap_argument_t *	arg,
		const char *	type_name
	)

Set the type name for an argument.

Must be one of the built-in types ("string", "int", "float", "bool") or a name previously registered with clap_register_type(). Default: "string".

Parameters

arg	Target argument.
type_name	Type name string (not copied — kept as-is).

Returns

arg for chaining.

clap_mutex_group_add_argument()

CLAP_EXPORT bool clap_mutex_group_add_argument	(	clap_parser_t *	parser,
		int	mutex_group_id,
		clap_argument_t *	arg
	)

Add an argument to a mutually exclusive group.

This also sets the argument's mutex group, so there is no need to call clap_argument_mutex_group() separately.

Parameters

parser	Target parser.
mutex_group_id	Group ID returned by clap_add_mutually_exclusive_group().
arg	Argument to add to the group.

Returns

true on success, false if mutex_group_id is invalid.

clap_namespace_append_string()

CLAP_EXPORT bool clap_namespace_append_string	(	clap_namespace_t *	ns,
		const char *	name,
		const char *	value
	)

Append a string to an array value in the namespace. Creates the array if the key does not exist yet.

Parameters

ns	Target namespace.
name	Destination key.
value	String to append (copied internally).

Returns

true on success, false on allocation failure.

clap_namespace_free()

CLAP_EXPORT void clap_namespace_free

(

clap_namespace_t *

ns

)

Free a namespace and all values it contains. NULL-safe.

Parameters

ns	Namespace to free, or NULL (no-op).

clap_namespace_get_bool()

CLAP_EXPORT bool clap_namespace_get_bool	(	clap_namespace_t *	ns,
		const char *	name,
		bool *	value
	)

Retrieve a bool value from the namespace.

Parameters

ns	Target namespace.
name	Destination key.
value	Receives the bool value.

Returns

true if the key exists and is a bool, false otherwise.

clap_namespace_get_float()

CLAP_EXPORT bool clap_namespace_get_float	(	clap_namespace_t *	ns,
		const char *	name,
		double *	value
	)

Retrieve a float value from the namespace.

Parameters

ns	Target namespace.
name	Destination key.
value	Receives the double value.

Returns

true if the key exists and is a float, false otherwise.

clap_namespace_get_int()

CLAP_EXPORT bool clap_namespace_get_int	(	clap_namespace_t *	ns,
		const char *	name,
		int *	value
	)

Retrieve an int value from the namespace.

Parameters

ns	Target namespace.
name	Destination key.
value	Receives the integer value.

Returns

true if the key exists and is an int, false otherwise.

clap_namespace_get_string()

CLAP_EXPORT bool clap_namespace_get_string	(	clap_namespace_t *	ns,
		const char *	name,
		const char **	value
	)

Retrieve a string value from the namespace.

Parameters

ns	Target namespace.
name	Destination key.
value	Receives a pointer to the internal string. Do not free.

Returns

true if the key exists and is a string, false otherwise.

clap_namespace_get_string_array()

CLAP_EXPORT bool clap_namespace_get_string_array	(	clap_namespace_t *	ns,
		const char *	name,
		const char ***	values,
		size_t *	count
	)

Retrieve a string array from the namespace (APPEND action).

Parameters

ns	Target namespace.
name	Destination key.
values	Receives a pointer to the internal string array. Do not modify or free.
count	Receives the number of elements.

Returns

true if the key exists and is an array, false otherwise.

clap_namespace_has()

CLAP_EXPORT bool clap_namespace_has	(	clap_namespace_t *	ns,
		const char *	name
	)

Check if a key exists in the namespace.

Unlike the typed getters (clap_namespace_get_*), this function returns true regardless of the value's type. Use it to test whether an argument was provided before calling a typed getter.

Parameters

ns	Target namespace.
name	Destination key.

Returns

true if the key exists with any type, false otherwise.

clap_namespace_set_bool()

CLAP_EXPORT bool clap_namespace_set_bool	(	clap_namespace_t *	ns,
		const char *	name,
		bool	value
	)

Set a bool value in the namespace.

Parameters

ns	Target namespace.
name	Destination key.
value	Bool value to store.

Returns

true on success, false on allocation failure.

clap_namespace_set_float()

CLAP_EXPORT bool clap_namespace_set_float	(	clap_namespace_t *	ns,
		const char *	name,
		double	value
	)

Set a float value in the namespace.

Parameters

ns	Target namespace.
name	Destination key.
value	Double value to store.

Returns

true on success, false on allocation failure.

clap_namespace_set_int()

CLAP_EXPORT bool clap_namespace_set_int	(	clap_namespace_t *	ns,
		const char *	name,
		int	value
	)

Set an int value in the namespace.

Parameters

ns	Target namespace.
name	Destination key.
value	Integer value to store.

Returns

true on success, false on allocation failure.

clap_namespace_set_string()

CLAP_EXPORT bool clap_namespace_set_string	(	clap_namespace_t *	ns,
		const char *	name,
		const char *	value
	)

Set a string value in the namespace.

Parameters

ns	Target namespace.
name	Destination key.
value	NUL-terminated string to copy.

Returns

true on success, false on allocation failure.

clap_parse_args()

CLAP_EXPORT clap_parse_result_t clap_parse_args	(	clap_parser_t *	parser,
		int	argc,
		char *	argv[],
		clap_namespace_t **	out_namespace,
		clap_error_t *	error
	)

Parse command-line arguments.

Tokenizes argv, analyzes the token pattern, runs the state- machine parser, validates all constraints (required args, mutex groups, dependencies, nargs), and writes results into a new namespace.

Parameters

parser	The configured parser.
argc	Argument count (from main()).
argv	Argument vector (from main()). argv[0] is the program name and is not parsed as an option.
out_namespace	On success, receives a newly allocated namespace containing all parsed values. Free with clap_namespace_free(). Not modified on error.
error	Set on CLAP_PARSE_ERROR with details. Not modified for HELP/VERSION/SUCCESS results.

Returns

CLAP_PARSE_SUCCESS on success, CLAP_PARSE_ERROR on failure, CLAP_PARSE_HELP if –help/-h was given (help already printed to stdout), CLAP_PARSE_VERSION similarly.

clap_parser_free()

CLAP_EXPORT void clap_parser_free

(

clap_parser_t *

parser

)

Destroy a parser and all resources it owns.

Frees every argument, group, subparser, type registry entry, and internal buffer associated with parser. Safely handles NULL.

Parameters

parser

Parser to free, or NULL (no-op).

clap_parser_new()

CLAP_EXPORT clap_parser_t * clap_parser_new	(	const char *	prog_name,
		const char *	description,
		const char *	epilog
	)

Create a new argument parser.

Parameters

prog_name	Program name shown in usage/help (e.g. "git").
description	Text shown after the usage line in help output. May be NULL.
epilog	Text shown after all argument sections in help. May be NULL.

Returns

New parser, or NULL on allocation failure. Free with clap_parser_free().

clap_parser_set_allow_abbrev()

CLAP_EXPORT void clap_parser_set_allow_abbrev	(	clap_parser_t *	parser,
		bool	allow
	)

Enable or disable abbreviated option matching.

When enabled, "--ver" will match "--verbose" if no other option shares the prefix. Default: disabled.

Parameters

parser	Target parser.
allow	true to enable prefix abbreviation matching.

clap_parser_set_help_width()

CLAP_EXPORT void clap_parser_set_help_width	(	clap_parser_t *	parser,
		int	width
	)

Set help output width (default: 100).

Parameters

parser	Target parser.
width	Width in characters. Clamped to [40, 500].

clap_parser_set_version()

CLAP_EXPORT void clap_parser_set_version	(	clap_parser_t *	parser,
		const char *	version
	)

Set the version string printed by clap_print_version().

Parameters

parser	Target parser.
version	Version string to display. May be NULL to clear.

clap_print_help()

CLAP_EXPORT void clap_print_help	(	clap_parser_t *	parser,
		FILE *	stream
	)

Print the full help text (usage + all sections) to a stream.

Composes the usage line, description, positional arguments, optional arguments, display groups, subcommands, and epilog, with smart word-wrapping at the configured width.

Parameters

parser	Target parser.
stream	Output stream (e.g. stdout, stderr).

clap_print_help_on_error()

CLAP_EXPORT void clap_print_help_on_error	(	clap_parser_t *	parser,
		const clap_error_t *	error,
		FILE *	stream
	)

Print "<prog>: error: <message>" and contextual help.

Prints a one-line error prefix (using the parser's program name and the error message), then:

• If the error occurred inside a subcommand (error->subcommand_name is set), prints help for that subcommand.
• Otherwise prints the parser's full help.

Typically called after clap_parse_args() returns CLAP_PARSE_ERROR.

Parameters

parser	Target parser.
error	Error struct from clap_parse_args().
stream	Output stream (e.g. stdout, stderr).

clap_print_subcommand_help()

CLAP_EXPORT bool clap_print_subcommand_help	(	clap_parser_t *	parser,
		const char *	command_name,
		FILE *	stream
	)

Print help for a specific subcommand to a stream.

Parameters

parser	Target parser (the parent).
command_name	Subcommand name.
stream	Output stream (e.g. stdout, stderr).

Returns

true on success, false if command_name is not found.

clap_print_version()

CLAP_EXPORT void clap_print_version	(	clap_parser_t *	parser,
		FILE *	stream
	)

Print "progname version X.Y.Z" to a stream.

The version string is the one set by clap_parser_set_version(). Falls back to "unknown" if no version was set.

Parameters

parser	Target parser.
stream	Output stream.

clap_register_type()

CLAP_EXPORT bool clap_register_type	(	clap_parser_t *	parser,
		const char *	type_name,
		clap_type_handler_t	handler,
		size_t	output_size
	)

Register a custom type validator/converter.

After registration, arguments can use this type name with clap_argument_type(). Custom type handlers are resolved at parse time. If a type name is used but never registered, clap_parse_args() returns CLAP_PARSE_ERROR with code CLAP_ERR_TYPE_CONVERSION and message "Unknown type".

Note

Custom type handlers are used for input validation. The handler's converted output is not persisted — the raw string is always stored in the namespace (retrievable via clap_namespace_get_string()). Use CLAP_ACTION_CUSTOM if you need to persist a typed conversion result.

Parameters

parser	Target parser.
type_name	Type name (e.g. "ip_addr", "regex").
handler	Validation function: const char* → typed value. Return false to reject the input.
output_size	Size of the output buffer in bytes (e.g. sizeof(my_type_t)).

Returns

true on success, false if type_name duplicates an existing entry or allocation fails.

clap_subparser_add()

CLAP_EXPORT clap_parser_t * clap_subparser_add	(	clap_parser_t *	subparsers,
		const char *	name,
		const char *	help_text
	)

Register a subcommand.

The new subparser inherits its help width and abbreviation setting from the parent. Add arguments to it with clap_add_argument().

Parameters

subparsers	The container returned by clap_add_subparsers().
name	Subcommand name (e.g. "commit", "push").
help_text	Help text shown in the "Commands:" section.

Returns

A new parser for the subcommand, or NULL on failure.

clap_subparsers_metavar()

CLAP_EXPORT void clap_subparsers_metavar	(	clap_parser_t *	parser,
		const char *	metavar
	)

Override the metavar shown for subcommands in the usage line.

Parameters

parser	Target parser (the parent, not the container).
metavar	Metavar string (e.g. "COMMAND"). If NULL, the metavar defaults to "{cmd1,cmd2,...}".