options.c File Reference

⚙️ Main entry point for unified options parsing with mode detection More...

Go to the source code of this file.

Data Structures
struct	binary_level_opts_t
	Create a new options_t struct with all defaults set. More...
struct	binary_actions_t
struct	mode_arguments_t
	The useful part of binary actions is in show_version, create_config, create_manpage, has_action: together they describe what is pending, who owns it, and how much data is valid. Keep the object with its parent operation and use the parent cleanup path. More...

Macros
#define	OPTIONS_OPT_BUFFER_SIZE   64
#define	OPTIONS_LOG_FILENAME_BUFFER_SIZE   256
#define	OPTIONS_RESULT_BUFFER_SIZE   512
#define	OPTIONS_LONG_FORM_BUFFER_SIZE   256
#define	OPTIONS_LONG_FORM_EQ_BUFFER_SIZE   256
#define	OPTIONS_NORMALIZED_URL_BUFFER_SIZE   2048

Functions
bool	has_action_flag (void)
	Check if an action flag was detected.
options_t	options_t_new (void)
	Initialize options by parsing command-line arguments.
options_t	options_t_new_preserve_binary (const options_t *source)
	Create a new options_t struct with all defaults set.
asciichat_error_t	options_init (int argc, char **argv)
	Initialize options by parsing command-line arguments with unified mode detection.
void	options_resolve_flip_x (options_t *opts)

Detailed Description

⚙️ Main entry point for unified options parsing with mode detection

Purpose: Implements options_init() - the unified entry point that:

1. Detects mode from command-line arguments (server, client, mirror, acds, etc.)
2. Parses binary-level options (–help, –version, –log-file, etc.)
3. Routes to mode-specific parsing using preset configurations
4. Loads configuration files if –config specified
5. Validates all options with cross-field checks
6. Publishes options via RCU for lock-free thread-safe access

Initialization order:

1. Validate argv and initialize RCU state.
2. Handle help, scan binary actions, and detect the mode.
3. Parse binary options and build argv for the selected mode.
4. Initialize mode defaults, build the schema, and load configuration files.
5. Parse mode options while preserving binary settings and track explicit flags.
6. Publish options for cleanup, validate them, and apply mode defaults.
7. Finalize identity keys, dimensions, and media settings.
8. Publish final options, apply the logging color scheme, and run deferred actions.

The stage helpers borrow options and parser state. options_init() owns the unified configuration and filtered argv array and releases both on errors. The configuration is released after validation; argv survives deferred actions.

Error Handling:

• Invalid options → ERROR_USAGE (usage already printed to stderr)
• File errors → ERROR_IO or ERROR_CONFIG
• Validation failures → ERROR_VALIDATION with context message
• Success → ASCIICHAT_OK

Thread Safety:

• options_init() must be called exactly once before worker threads
• After options_init() completes, options are read-only
• Access via lock-free GET_OPTION() macro from worker threads
• Optional updates via options_set_*() functions

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Definition in file options.c.

Macro Definition Documentation

OPTIONS_LOG_FILENAME_BUFFER_SIZE

#define OPTIONS_LOG_FILENAME_BUFFER_SIZE   256

Definition at line 50 of file options.c.

OPTIONS_LONG_FORM_BUFFER_SIZE

#define OPTIONS_LONG_FORM_BUFFER_SIZE   256

Definition at line 52 of file options.c.

OPTIONS_LONG_FORM_EQ_BUFFER_SIZE

#define OPTIONS_LONG_FORM_EQ_BUFFER_SIZE   256

Definition at line 53 of file options.c.

OPTIONS_NORMALIZED_URL_BUFFER_SIZE

#define OPTIONS_NORMALIZED_URL_BUFFER_SIZE   2048

Definition at line 54 of file options.c.

OPTIONS_OPT_BUFFER_SIZE

#define OPTIONS_OPT_BUFFER_SIZE   64

Definition at line 49 of file options.c.

OPTIONS_RESULT_BUFFER_SIZE

#define OPTIONS_RESULT_BUFFER_SIZE   512

Definition at line 51 of file options.c.

Function Documentation

options_resolve_flip_x()

void options_resolve_flip_x

(

options_t *

opts

)

Resolve source defaults without turning them into a user selection.

Definition at line 2575 of file options.c.

                                             {
  if (!opts->flip_x_explicit)
    opts->flip_x = !opts->media_input && !opts->test_pattern && !opts->waveform && !opts->fft;
}

References options_state::fft, options_state::flip_x, options_state::flip_x_explicit, options_state::media_input, options_state::test_pattern, and options_state::waveform.

Referenced by options_prepare_patch(), and options_state_set().

options_t_new_preserve_binary()

options_t options_t_new_preserve_binary

(

const options_t *

source

)

Create a new options_t struct with all defaults set.

Create new options struct, preserving binary-level fields from source

This version of options_t_new() extracts binary-level options from a source struct before performing a full reset, then restores them after. This allows binary-level options (–quiet, –verbose, –log-level, etc.) to persist through multiple reset cycles without manual save/restore code.

Parameters

source

The options struct to extract binary-level fields from (NULL-safe)

Returns

New options_t with defaults and binary-level fields preserved

Definition at line 765 of file options.c.

                                                                 {
  // Extract binary-level options before reset
  binary_level_opts_t binary = extract_binary_level(source);
 
  // Create fresh options with all defaults
  options_t opts = options_t_new();
 
  // Restore binary-level options (overwrite defaults)
  restore_binary_level(&opts, &binary);
 
  return opts;
}

References options_t_new(), and source.