actions.h File Reference

Action option callbacks for ascii-chat. More...

Go to the source code of this file.

Data Structures
struct	action_args_t
	Action argument structure. More...

Enumerations
enum	deferred_action_t {   ACTION_NONE = 0 , ACTION_LIST_WEBCAMS , ACTION_LIST_MICROPHONES , ACTION_LIST_SPEAKERS ,   ACTION_SHOW_CAPABILITIES , ACTION_CHECK_UPDATE }
	Action type enumeration. More...

Functions
void	actions_defer (deferred_action_t action, const action_args_t *args)
	Set which action to defer until options are fully initialized.
deferred_action_t	actions_get_deferred (void)
	Get the deferred action (if any) that was set.
const action_args_t *	actions_get_args (void)
	Get the arguments for the deferred action.
void	actions_execute_deferred (void)
	Execute the deferred action (if any)
void	action_list_webcams (void)
	List available webcam devices and exit.
void	action_list_microphones (void)
	List available microphone devices and exit.
void	action_list_speakers (void)
	List available speaker devices and exit.
void	action_show_capabilities (void)
	Show terminal capabilities and exit.
void	action_show_capabilities_immediate (void)
	Execute show capabilities immediately (for binary-level execution)
void	action_show_version (void)
	Show version information and exit.
void	action_help_server (void)
	Show server mode help and exit.
void	action_help_client (void)
	Show client mode help and exit.
void	action_help_mirror (void)
	Show mirror mode help and exit.
void	action_help_acds (void)
	Show discovery-service mode help and exit.
void	action_help_discovery (void)
	Show discovery mode help and exit.
void	action_create_manpage (const char *output_path)
	Generate man page template from options builder.
void	action_create_config (const char *output_path)
	Create default configuration file and exit.
void	action_completions (const char *shell_name, const char *output_path)
	Generate shell completions and output to stdout or file.
void	action_check_update (void)
	Check for updates and display results.
void	action_check_update_immediate (void)
	Execute update check immediately (for binary-level execution)

Detailed Description

Action option callbacks for ascii-chat.

Definition in file actions.h.

Enumeration Type Documentation

deferred_action_t

enum deferred_action_t

Action type enumeration.

Defines all possible deferred actions that can be executed after options are fully parsed and initialized.

Enumerator
ACTION_NONE
ACTION_LIST_WEBCAMS
ACTION_LIST_MICROPHONES
ACTION_LIST_SPEAKERS
ACTION_SHOW_CAPABILITIES
ACTION_CHECK_UPDATE

Definition at line 17 of file actions.h.

             {
  ACTION_NONE = 0,
  ACTION_LIST_WEBCAMS,
  ACTION_LIST_MICROPHONES,
  ACTION_LIST_SPEAKERS,
  ACTION_SHOW_CAPABILITIES,
  ACTION_CHECK_UPDATE,
} deferred_action_t;

Function Documentation

action_check_update()

void action_check_update

(

void

)

Check for updates and display results.

Performs update check against GitHub releases API and displays results. Exits with code 0 on success, 1 on error.

Definition at line 329 of file options/parsing/actions.c.

                               {
  // Defer execution until after options are fully parsed
  actions_defer(ACTION_CHECK_UPDATE, NULL);
}

References ACTION_CHECK_UPDATE, and actions_defer().

Referenced by options_registry_add_all_to_builder().

action_check_update_immediate()

void action_check_update_immediate

(

void

)

Execute update check immediately (for binary-level execution)

Performs immediate update check and exits. Used when –check-update is specified before mode detection. Exits with code 0 on success, 1 on error.

Execute update check immediately (for binary-level execution)

Definition at line 311 of file options/parsing/actions.c.

                                         {
  printf("Checking for updates...\n");
  update_check_result_t result;
  asciichat_error_t err = update_check_perform(&result);
  if (err != ASCIICHAT_OK) {
    printf("\nFailed to check for updates.\n\n");
    action_exit(1);
  }
  if (result.update_available) {
    char notification[1024];
    update_check_format_notification(&result, notification, sizeof(notification));
    printf("\n%s\n\n", notification);
  } else {
    printf("\nYou are already on the latest version: %s (%.8s)\n\n", result.current_version, result.current_sha);
  }
  action_exit(0);
}

References ASCIICHAT_OK, update_check_result_t::current_sha, update_check_result_t::current_version, update_check_result_t::update_available, update_check_format_notification(), and update_check_perform().

Referenced by options_init().

action_completions()

void action_completions	(	const char *	shell_name,
		const char *	output_path
	)

Generate shell completions and output to stdout or file.

Generates shell completion script for the specified shell (bash, fish, zsh, powershell). Output is dynamically generated from the options registry, ensuring completions are always in sync with current options. Outputs to stdout by default, or to specified file path if provided. Prompts for overwrite confirmation if file already exists. Exits with code 0 on success, 1 on error.

Parameters

shell_name	Shell name: "bash", "fish", "zsh", or "powershell"
output_path	Optional file path to write completions to. NULL or empty string = stdout.

Definition at line 571 of file options/parsing/actions.c.

                                                                         {
  if (!shell_name || strlen(shell_name) == 0) {
    log_error("--completions requires shell name (bash, fish, zsh, powershell)");
    action_exit(ERROR_USAGE);
  }
 
  completion_format_t format = completions_parse_shell_name(shell_name);
  if (format == COMPLETION_FORMAT_UNKNOWN) {
    log_error("Unknown shell '%s' (supported: bash, fish, zsh, powershell)", shell_name);
    action_exit(ERROR_USAGE);
  }
 
  FILE *output = stdout;
  bool should_close = false;
 
  // Determine output: use provided path if given and not "-", otherwise stdout
  if (output_path && strlen(output_path) > 0 && strcmp(output_path, "-") != 0) {
    // Check if file already exists and prompt for confirmation
    struct stat st;
    if (stat(output_path, &st) == 0) {
      // File exists - ask user if they want to overwrite
      log_plain("Completions file already exists: %s", output_path);
 
      bool overwrite = platform_prompt_yes_no("Overwrite", false); // Default to No
      if (!overwrite) {
        log_plain("Completions generation cancelled.");
        action_exit(0);
      }
 
      log_plain("Overwriting existing completions file...");
    }
 
    output = platform_fopen("file_stream", output_path, "w");
    if (!output) {
      log_error("Failed to open %s for writing", output_path);
      action_exit(ERROR_FILE_OPERATION);
    }
    should_close = true;
  }
 
  asciichat_error_t result = completions_generate_for_shell(format, output);
 
  if (should_close) {
    fclose(output);
  }
 
  if (result != ASCIICHAT_OK) {
    log_error("Failed to generate %s completions", completions_get_shell_name(format));
    action_exit(ERROR_USAGE);
  }
 
  // Silently exit - completions are written (either to file or stdout)
  action_exit(0);
}

References ASCIICHAT_OK, COMPLETION_FORMAT_UNKNOWN, completions_generate_for_shell(), completions_get_shell_name(), completions_parse_shell_name(), ERROR_FILE_OPERATION, ERROR_USAGE, log_error, log_plain, platform_fopen(), and platform_prompt_yes_no().

Referenced by options_init().

action_create_config()

void action_create_config

(

const char *

output_path

)

Create default configuration file and exit.

Creates a default configuration file. Outputs to stdout by default, or to specified file path if provided. Prompts for overwrite confirmation if file already exists. Exits with code 0 on success, 1 on error.

Parameters

output_path

Optional file path to write config to. NULL or empty string = stdout.

Definition at line 524 of file options/parsing/actions.c.

                                                   {
  // Build the schema first so config_create_default can generate options from it
  const options_config_t *unified_config = options_preset_unified(NULL, NULL);
  if (unified_config) {
    asciichat_error_t schema_build_result = config_schema_build_from_configs(&unified_config, 1);
    if (schema_build_result != ASCIICHAT_OK) {
      // Schema build failed, but continue anyway
      (void)schema_build_result;
    }
    // options_config_destroy(unified_config);
  }
 
  const char *config_path = NULL;
 
  // Determine output path: use provided path, or NULL for stdout
  if (output_path && strlen(output_path) > 0 && strcmp(output_path, "-") != 0) {
    // User provided explicit path - use it as-is
    config_path = output_path;
  } else {
    // No path or "-" means stdout
    config_path = NULL;
  }
 
  // Create config with default options
  asciichat_error_t result = config_create_default(config_path);
  if (result != ASCIICHAT_OK) {
    asciichat_error_context_t err_ctx;
    if (HAS_ERRNO(&err_ctx)) {
      log_error("Error creating config: %s", err_ctx.context_message);
    } else {
      log_error("Failed to create config file");
    }
    action_exit(ERROR_CONFIG);
  }
 
  if (config_path) {
    log_info("Created default config file at: %s", config_path);
  } else {
    log_info("Config written to stdout");
  }
  action_exit(0);
}

References ASCIICHAT_OK, config_create_default(), config_schema_build_from_configs(), asciichat_error_context_t::context_message, ERROR_CONFIG, HAS_ERRNO, log_error, log_info, and options_preset_unified().

Referenced by options_init().

action_create_manpage()

void action_create_manpage

(

const char *

output_path

)

Generate man page template from options builder.

Generates a merged man page template preserving manual content. Outputs to stdout by default, or to specified file path if provided. Prompts for overwrite confirmation if file already exists. Exits with code 0 on success, 1 on error.

Parameters

output_path

Optional file path to write man page to. NULL or empty string = stdout.

Definition at line 475 of file options/parsing/actions.c.

                                                    {
  // Get binary-level config
  const options_config_t *config = options_preset_unified(NULL, NULL);
 
  if (!config) {
    log_error("Failed to get binary options config");
    action_exit(ERROR_FILE_OPERATION);
  }
 
  // Determine output path: use provided path, or NULL for stdout
  const char *path_to_use = NULL;
  if (output_path && strlen(output_path) > 0 && strcmp(output_path, "-") != 0) {
    // User provided explicit path - use it
    path_to_use = output_path;
  } else {
    // No path or "-" means stdout
    path_to_use = NULL;
  }
 
  // Generate merged man page from embedded or filesystem resources
  // Resources are loaded automatically based on build type:
  // - Production (Release): From embedded binary data
  // - Development (Debug): From filesystem files
  asciichat_error_t err =
      options_config_generate_manpage_merged(config, "ascii-chat", NULL, path_to_use, "Video chat in your terminal");
 
  if (err != ASCIICHAT_OK) {
    asciichat_error_context_t err_ctx;
    if (HAS_ERRNO(&err_ctx)) {
      log_error("%s", err_ctx.context_message);
    } else {
      log_error("Failed to generate man page");
    }
    action_exit(ERROR_FILE_OPERATION);
  }
 
  if (path_to_use) {
    log_info("Man page written to: %s", path_to_use);
  } else {
    log_info("Man page written to stdout");
  }
 
  action_exit(0);
}

References ASCIICHAT_OK, asciichat_error_context_t::context_message, ERROR_FILE_OPERATION, HAS_ERRNO, log_error, log_info, options_config_generate_manpage_merged(), and options_preset_unified().

Referenced by options_init().

action_help_acds()

void action_help_acds

(

void

)

Show discovery-service mode help and exit.

Displays discovery-service mode usage and options. Exits with code 0.

Definition at line 461 of file options/parsing/actions.c.

                            {
  usage(stdout, MODE_DISCOVERY_SERVICE);
  action_exit(0);
}

References MODE_DISCOVERY_SERVICE, and usage().

action_help_client()

void action_help_client

(

void

)

Show client mode help and exit.

Displays client mode usage and options. Exits with code 0.

Definition at line 451 of file options/parsing/actions.c.

                              {
  usage(stdout, MODE_CLIENT);
  action_exit(0);
}

References MODE_CLIENT, and usage().

action_help_discovery()

void action_help_discovery

(

void

)

Show discovery mode help and exit.

Displays discovery mode usage and options. Exits with code 0.

Definition at line 466 of file options/parsing/actions.c.

                                 {
  usage(stdout, MODE_DISCOVERY);
  action_exit(0);
}

References MODE_DISCOVERY, and usage().

action_help_mirror()

void action_help_mirror

(

void

)

Show mirror mode help and exit.

Displays mirror mode usage and options. Exits with code 0.

Definition at line 456 of file options/parsing/actions.c.

                              {
  usage(stdout, MODE_MIRROR);
  action_exit(0);
}

References MODE_MIRROR, and usage().

action_help_server()

void action_help_server

(

void

)

Show server mode help and exit.

Displays server mode usage and options. Exits with code 0.

Definition at line 446 of file options/parsing/actions.c.

                              {
  usage(stdout, MODE_SERVER);
  action_exit(0);
}

References MODE_SERVER, and usage().

action_list_microphones()

void action_list_microphones

(

void

)

List available microphone devices and exit.

Enumerates all audio input devices and prints them to stdout. Exits with code 0 on success, 1 on error.

Definition at line 145 of file options/parsing/actions.c.

                                   {
  // Defer execution until after options are fully parsed
  actions_defer(ACTION_LIST_MICROPHONES, NULL);
}

References ACTION_LIST_MICROPHONES, and actions_defer().

Referenced by options_init(), and options_registry_add_all_to_builder().

action_list_speakers()

void action_list_speakers

(

void

)

List available speaker devices and exit.

Enumerates all audio output devices and prints them to stdout. Exits with code 0 on success, 1 on error.

Definition at line 183 of file options/parsing/actions.c.

                                {
  // Defer execution until after options are fully parsed
  actions_defer(ACTION_LIST_SPEAKERS, NULL);
}

References ACTION_LIST_SPEAKERS, and actions_defer().

Referenced by options_init(), and options_registry_add_all_to_builder().

action_list_webcams()

void action_list_webcams

(

void

)

List available webcam devices and exit.

Enumerates all webcam devices and prints them to stdout. Exits with code 0 on success, 1 on error.

Definition at line 107 of file options/parsing/actions.c.

                               {
  // Defer execution until after options are fully parsed
  actions_defer(ACTION_LIST_WEBCAMS, NULL);
}

References ACTION_LIST_WEBCAMS, and actions_defer().

Referenced by options_init(), and options_registry_add_all_to_builder().

action_show_capabilities()

void action_show_capabilities

(

void

)

Show terminal capabilities and exit.

Detects and displays terminal color support, UTF-8 support, dimensions, and terminal program name. Exits with code 0.

Note: This action is deferred until after all options are parsed and dimensions are calculated, so that –width and –height flags are properly reflected in the output.

Definition at line 298 of file options/parsing/actions.c.

                                    {
  // Defer execution until after options are fully parsed and dimensions updated
  // This ensures --width and --height flags are properly reflected in the output
  actions_defer(ACTION_SHOW_CAPABILITIES, NULL);
}

References ACTION_SHOW_CAPABILITIES, and actions_defer().

Referenced by options_registry_add_all_to_builder().

action_show_capabilities_immediate()

void action_show_capabilities_immediate

(

void

)

Execute show capabilities immediately (for binary-level execution)

Shows terminal capabilities before full options parsing. Uses detected terminal size (doesn't respect –width/–height). Exits with code 0.

Execute show capabilities immediately (for binary-level execution)

Definition at line 228 of file options/parsing/actions.c.

                                              {
  terminal_capabilities_t caps = detect_terminal_capabilities();
 
  // Determine if we should use colored output
  bool use_colors = terminal_should_color_output(STDOUT_FILENO);
 
  // Override color level if colors should not be shown
  if (!use_colors) {
    caps.color_level = TERM_COLOR_NONE;
    caps.color_count = 0;
    caps.capabilities &= ~((uint32_t)(TERM_CAP_COLOR_TRUE | TERM_CAP_COLOR_256 | TERM_CAP_COLOR_16));
  }
 
  // Use detected terminal size (immediate execution doesn't have parsed options yet)
  terminal_size_t size;
  terminal_get_size(&size);
  unsigned short width = size.cols;
  unsigned short height = size.rows;
 
  log_color_t label_color = use_colors ? LOG_COLOR_DEBUG : LOG_COLOR_GREY;
  log_color_t string_color = use_colors ? LOG_COLOR_DEBUG : LOG_COLOR_GREY;
  log_color_t good_color = use_colors ? LOG_COLOR_INFO : LOG_COLOR_GREY;
  log_color_t bad_color = use_colors ? LOG_COLOR_ERROR : LOG_COLOR_GREY;
  log_color_t number_color = use_colors ? LOG_COLOR_DEBUG : LOG_COLOR_GREY;
 
  printf("%s\n", colored_string(LOG_COLOR_WARN, "Terminal Capabilities:"));
 
  char size_buf[64];
  snprintf(size_buf, sizeof(size_buf), "%ux%u", width, height);
  printf("  %s: %s\n", colored_string(label_color, "Terminal Size"), colored_string(number_color, size_buf));
 
  const char *color_level_name = terminal_color_level_name(caps.color_level);
  log_color_t color_level_color = (caps.color_level == TERM_COLOR_NONE) ? bad_color : string_color;
  printf("  %s: %s\n", colored_string(label_color, "Color Level"),
         colored_string(color_level_color, (char *)color_level_name));
 
  char colors_buf[64];
  snprintf(colors_buf, sizeof(colors_buf), "%u", caps.color_count);
  printf("  %s: %s\n", colored_string(label_color, "Max Colors"), colored_string(number_color, colors_buf));
 
  log_color_t utf8_color = caps.utf8_support ? good_color : bad_color;
  printf("  %s: %s\n", colored_string(label_color, "UTF-8 Support"),
         colored_string(utf8_color, (char *)(caps.utf8_support ? "Yes" : "No")));
 
  const char *render_mode_str = "unknown";
  if (caps.render_mode == RENDER_MODE_FOREGROUND) {
    render_mode_str = "foreground";
  } else if (caps.render_mode == RENDER_MODE_BACKGROUND) {
    render_mode_str = "background";
  } else if (caps.render_mode == RENDER_MODE_HALF_BLOCK) {
    render_mode_str = "half-block";
  }
  printf("  %s: %s\n", colored_string(label_color, "Render Mode"),
         colored_string(string_color, (char *)render_mode_str));
  printf("  %s: %s\n", colored_string(label_color, "TERM"), colored_string(string_color, (char *)caps.term_type));
  printf("  %s: %s\n", colored_string(label_color, "COLORTERM"),
         colored_string(string_color, (char *)(strlen(caps.colorterm) ? caps.colorterm : "(not set)")));
 
  log_color_t reliable_color = caps.detection_reliable ? good_color : bad_color;
  printf("  %s: %s\n", colored_string(label_color, "Detection Reliable"),
         colored_string(reliable_color, (char *)(caps.detection_reliable ? "Yes" : "No")));
 
  char bitmask_buf[64];
  snprintf(bitmask_buf, sizeof(bitmask_buf), "0x%08x", caps.capabilities);
  printf("  %s: %s\n", colored_string(label_color, "Capabilities Bitmask"), colored_string(number_color, bitmask_buf));
 
  fflush(stdout);
  action_exit(0);
}

References terminal_capabilities_t::capabilities, terminal_capabilities_t::color_count, terminal_capabilities_t::color_level, colored_string(), terminal_capabilities_t::colorterm, terminal_size_t::cols, detect_terminal_capabilities(), terminal_capabilities_t::detection_reliable, LOG_COLOR_DEBUG, LOG_COLOR_ERROR, LOG_COLOR_GREY, LOG_COLOR_INFO, LOG_COLOR_WARN, terminal_capabilities_t::render_mode, RENDER_MODE_BACKGROUND, RENDER_MODE_FOREGROUND, RENDER_MODE_HALF_BLOCK, terminal_size_t::rows, TERM_CAP_COLOR_16, TERM_CAP_COLOR_256, TERM_CAP_COLOR_TRUE, TERM_COLOR_NONE, terminal_capabilities_t::term_type, terminal_color_level_name(), terminal_get_size(), terminal_should_color_output(), and terminal_capabilities_t::utf8_support.

Referenced by options_init().

action_show_version()

void action_show_version

(

void

)

Show version information and exit.

Displays ascii-chat version, build type, build date, and compiler information. Exits with code 0.

Definition at line 428 of file options/parsing/actions.c.

                               {
  bool use_colors = terminal_should_color_output(STDOUT_FILENO);
  if (use_colors) {
    printf("%s %s (%s, %s)\n", colored_string(LOG_COLOR_WARN, "ascii-chat"),
           colored_string(LOG_COLOR_INFO, (char *)ASCII_CHAT_VERSION_FULL),
           colored_string(LOG_COLOR_DEBUG, (char *)ASCII_CHAT_BUILD_TYPE),
           colored_string(LOG_COLOR_GREY, (char *)ASCII_CHAT_BUILD_DATE));
  } else {
    printf("ascii-chat %s (%s, %s)\n", ASCII_CHAT_VERSION_FULL, ASCII_CHAT_BUILD_TYPE, ASCII_CHAT_BUILD_DATE);
  }
 
  action_exit(0);
}

References ASCII_CHAT_BUILD_DATE, ASCII_CHAT_BUILD_TYPE, ASCII_CHAT_VERSION_FULL, colored_string(), LOG_COLOR_DEBUG, LOG_COLOR_GREY, LOG_COLOR_INFO, LOG_COLOR_WARN, and terminal_should_color_output().

Referenced by main().

actions_defer()

void actions_defer	(	deferred_action_t	action,
		const action_args_t *	args
	)

Set which action to defer until options are fully initialized.

Only the first action found is remembered. If multiple actions are specified, only the first one will be executed.

Parameters

action	The action type to defer
args	Optional action arguments (can be NULL)

Definition at line 75 of file options/parsing/actions.c.

                                                                        {
  // Only remember the first action found
  if (g_deferred_action_state.has_action) {
    return; // Action already deferred, ignore subsequent actions
  }
 
  g_deferred_action_state.action = action;
  g_deferred_action_state.has_action = true;
 
  // Copy arguments if provided
  if (args) {
    memcpy(&g_deferred_action_state.args, args, sizeof(action_args_t));
  } else {
    memset(&g_deferred_action_state.args, 0, sizeof(action_args_t));
  }
}

References action, and args.

Referenced by action_check_update(), action_list_microphones(), action_list_speakers(), action_list_webcams(), and action_show_capabilities().

actions_execute_deferred()

void actions_execute_deferred

(

void

)

Execute the deferred action (if any)

This function should be called during STAGE 8 of options_init() after all options are fully parsed and dimensions are calculated.

Definition at line 662 of file options/parsing/actions.c.

                                    {
  deferred_action_t action = actions_get_deferred();
 
  switch (action) {
  case ACTION_NONE:
    // No action to execute
    break;
 
  case ACTION_LIST_WEBCAMS:
    execute_list_webcams();
    break;
 
  case ACTION_LIST_MICROPHONES:
    execute_list_microphones();
    break;
 
  case ACTION_LIST_SPEAKERS:
    execute_list_speakers();
    break;
 
  case ACTION_SHOW_CAPABILITIES:
    execute_show_capabilities();
    break;
 
  case ACTION_CHECK_UPDATE:
    execute_check_update();
    break;
 
  default:
    log_warn("Unknown deferred action: %d", action);
    break;
  }
}

References action, ACTION_CHECK_UPDATE, ACTION_LIST_MICROPHONES, ACTION_LIST_SPEAKERS, ACTION_LIST_WEBCAMS, ACTION_NONE, ACTION_SHOW_CAPABILITIES, actions_get_deferred(), and log_warn.

Referenced by options_init().

actions_get_args()

const action_args_t * actions_get_args

(

void

)

Get the arguments for the deferred action.

Returns

Pointer to action arguments, or NULL if no arguments were set

Definition at line 96 of file options/parsing/actions.c.

                                            {
  if (!g_deferred_action_state.has_action) {
    return NULL;
  }
  return &g_deferred_action_state.args;
}

actions_get_deferred()

deferred_action_t actions_get_deferred

(

void

)

Get the deferred action (if any) that was set.

Returns

The deferred action type, or ACTION_NONE if no action was deferred

Definition at line 92 of file options/parsing/actions.c.

                                             {
  return g_deferred_action_state.action;
}

Referenced by actions_execute_deferred().