completions.h File Reference

Auto-generated shell completions from options registry. More...

Go to the source code of this file.

Enumerations
enum	completion_format_t {   COMPLETION_FORMAT_BASH , COMPLETION_FORMAT_FISH , COMPLETION_FORMAT_ZSH , COMPLETION_FORMAT_POWERSHELL ,   COMPLETION_FORMAT_UNKNOWN }
	Supported shell completion formats. More...

Functions
asciichat_error_t	completions_generate_for_shell (completion_format_t format, FILE *output)
	Generate shell completions and write to output stream.
const char *	completions_get_shell_name (completion_format_t format)
	Get human-readable shell name for format.
completion_format_t	completions_parse_shell_name (const char *shell_name)
	Parse shell name string to completion format.
option_descriptor_t *	completions_collect_all_modes_unique (size_t *count)
	Collect options from all modes with deduplication.

Detailed Description

Auto-generated shell completions from options registry.

This module provides auto-generated completion scripts for various shells (bash, fish, zsh, powershell) by extracting option metadata from the centralized options registry.

Usage:

# Generate bash completions
eval "$(ascii-chat --completions bash)"
 
# Generate fish completions
ascii-chat --completions fish | source
 
# Generate zsh completions
eval "$(ascii-chat --completions zsh)"
 
# Generate PowerShell completions
ascii-chat --completions powershell | Out-String | Invoke-Expression

Architecture:

The completion system has three layers:

1. Format Enum (completion_format_t): Identifies target shell
2. Format Generators: Shell-specific implementations (bash.c, fish.c, etc.)
3. Dispatcher: Routes to appropriate generator based on format

All generators extract metadata from the centralized options registry via:

• options_registry_get_for_mode() - Get options by mode
• options_registry_find_by_name() - Look up individual options
• Option descriptor fields (long_name, short_name, help_text, mode_bitmask)

Adding New Shells:

To add support for a new shell:

1. Create lib/options/completions/SHELL_NAME.h and .c
2. Implement completions_generate_SHELL_NAME() function
3. Add case to completions_generate_for_shell() dispatcher
4. Update completion_parse_shell_name() to recognize new shell

Author

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

Date

January 2026

Definition in file completions.h.

Enumeration Type Documentation

completion_format_t

enum completion_format_t

Supported shell completion formats.

Enumerator
COMPLETION_FORMAT_BASH	Bash shell completion
COMPLETION_FORMAT_FISH	Fish shell completion
COMPLETION_FORMAT_ZSH	Zsh shell completion
COMPLETION_FORMAT_POWERSHELL	PowerShell completion
COMPLETION_FORMAT_UNKNOWN	Unknown/invalid format

Definition at line 66 of file completions.h.

             {
  COMPLETION_FORMAT_BASH,       
  COMPLETION_FORMAT_FISH,       
  COMPLETION_FORMAT_ZSH,        
  COMPLETION_FORMAT_POWERSHELL, 
  COMPLETION_FORMAT_UNKNOWN     
} completion_format_t;

Function Documentation

completions_collect_all_modes_unique()

option_descriptor_t * completions_collect_all_modes_unique

(

size_t *

count

)

Collect options from all modes with deduplication.

Iterates through all completion modes (MODE_DISCOVERY, MODE_SERVER, MODE_CLIENT, MODE_MIRROR, MODE_DISCOVERY_SERVICE) and collects unique options by long_name. Useful for generators that need to show completions for options across multiple modes.

Parameters

[out]

count

Pointer to receive the count of unique options

Returns

Dynamically allocated array of option_descriptor_t, must be freed by caller. Returns NULL if no options found.

Note

The caller must free the returned pointer with SAFE_FREE()

Definition at line 100 of file completions.c.

                                                                         {
  if (!count) {
    return NULL;
  }
 
  option_descriptor_t *combined_opts = NULL;
  size_t combined_count = 0;
 
  /* All completion modes to iterate through */
  asciichat_mode_t modes[] = {MODE_DISCOVERY,         MODE_SERVER,    MODE_CLIENT, MODE_MIRROR,
                              MODE_DISCOVERY_SERVICE, MODE_MCP_SERVER};
  const size_t modes_len = sizeof(modes) / sizeof(modes[0]);
 
  for (size_t m = 0; m < modes_len; m++) {
    size_t mode_count = 0;
    const option_descriptor_t *mode_opts = options_registry_get_for_mode(modes[m], &mode_count);
    if (mode_opts) {
      /* Collect unique options by long_name */
      for (size_t i = 0; i < mode_count; i++) {
        bool already_has = false;
        for (size_t j = 0; j < combined_count; j++) {
          if (strcmp(combined_opts[j].long_name, mode_opts[i].long_name) == 0) {
            already_has = true;
            break;
          }
        }
        if (!already_has) {
          combined_count++;
          option_descriptor_t *temp = (option_descriptor_t *)SAFE_REALLOC(
              combined_opts, combined_count * sizeof(option_descriptor_t), option_descriptor_t *);
          if (temp) {
            combined_opts = temp;
            combined_opts[combined_count - 1] = mode_opts[i];
          }
        }
      }
      SAFE_FREE(mode_opts);
    }
  }
 
  *count = combined_count;
  return combined_opts;
}

References MODE_CLIENT, MODE_DISCOVERY, MODE_DISCOVERY_SERVICE, MODE_MCP_SERVER, MODE_MIRROR, MODE_SERVER, options_registry_get_for_mode(), SAFE_FREE, and SAFE_REALLOC.

completions_generate_for_shell()

asciichat_error_t completions_generate_for_shell	(	completion_format_t	format,
		FILE *	output )

Generate shell completions and write to output stream.

Generates a complete shell completion script for the specified shell format by extracting option metadata from the centralized registry.

Parameters

format	Shell format to generate completions for
output	FILE stream to write completion script to (e.g., stdout)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 24 of file completions.c.

                                                                                           {
  if (!output) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Output stream cannot be NULL");
  }
 
  switch (format) {
  case COMPLETION_FORMAT_BASH:
    return completions_generate_bash(output);
  case COMPLETION_FORMAT_FISH:
    return completions_generate_fish(output);
  case COMPLETION_FORMAT_ZSH:
    return completions_generate_zsh(output);
  case COMPLETION_FORMAT_POWERSHELL:
    return completions_generate_powershell(output);
  default:
    return SET_ERRNO(ERROR_INVALID_PARAM, "Unknown completion format: %d", format);
  }
}

References COMPLETION_FORMAT_BASH, COMPLETION_FORMAT_FISH, COMPLETION_FORMAT_POWERSHELL, COMPLETION_FORMAT_ZSH, completions_generate_bash(), completions_generate_fish(), completions_generate_powershell(), completions_generate_zsh(), ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by action_completions().

completions_get_shell_name()

const char * completions_get_shell_name

(

completion_format_t

format

)

Get human-readable shell name for format.

Parameters

format

Completion format

Returns

Shell name string (e.g., "bash", "fish"), or "unknown" if invalid

Definition at line 43 of file completions.c.

                                                                   {
  switch (format) {
  case COMPLETION_FORMAT_BASH:
    return OPT_COMPLETION_SHELL_BASH;
  case COMPLETION_FORMAT_FISH:
    return OPT_COMPLETION_SHELL_FISH;
  case COMPLETION_FORMAT_ZSH:
    return OPT_COMPLETION_SHELL_ZSH;
  case COMPLETION_FORMAT_POWERSHELL:
    return OPT_COMPLETION_SHELL_POWERSHELL;
  default:
    return "unknown";
  }
}

References COMPLETION_FORMAT_BASH, COMPLETION_FORMAT_FISH, COMPLETION_FORMAT_POWERSHELL, COMPLETION_FORMAT_ZSH, OPT_COMPLETION_SHELL_BASH, OPT_COMPLETION_SHELL_FISH, OPT_COMPLETION_SHELL_POWERSHELL, and OPT_COMPLETION_SHELL_ZSH.

Referenced by action_completions().

completions_parse_shell_name()

completion_format_t completions_parse_shell_name

(

const char *

shell_name

)

Parse shell name string to completion format.

Converts a shell name (e.g., "bash", "fish") to the corresponding completion format enum. Case-insensitive.

Parameters

shell_name

Shell name string (e.g., "bash", "fish", "zsh")

Returns

Completion format, or COMPLETION_FORMAT_UNKNOWN if not recognized

Definition at line 58 of file completions.c.

                                                                         {
  if (!shell_name) {
    return COMPLETION_FORMAT_UNKNOWN;
  }
 
  /* Convert to lowercase for case-insensitive matching */
  char lower[OPTIONS_COMPLETIONS_LOWER_BUFFER_SIZE] = {0};
  size_t len = strlen(shell_name);
  if (len >= sizeof(lower)) {
    return COMPLETION_FORMAT_UNKNOWN;
  }
 
  for (size_t i = 0; i < len; i++) {
    lower[i] = tolower((unsigned char)shell_name[i]);
  }
 
  if (strcmp(lower, OPT_COMPLETION_SHELL_BASH) == 0) {
    return COMPLETION_FORMAT_BASH;
  } else if (strcmp(lower, OPT_COMPLETION_SHELL_FISH) == 0) {
    return COMPLETION_FORMAT_FISH;
  } else if (strcmp(lower, OPT_COMPLETION_SHELL_ZSH) == 0) {
    return COMPLETION_FORMAT_ZSH;
  } else if (strcmp(lower, OPT_COMPLETION_SHELL_POWERSHELL) == 0 || strcmp(lower, "ps") == 0) {
    return COMPLETION_FORMAT_POWERSHELL;
  }
 
  return COMPLETION_FORMAT_UNKNOWN;
}

References COMPLETION_FORMAT_BASH, COMPLETION_FORMAT_FISH, COMPLETION_FORMAT_POWERSHELL, COMPLETION_FORMAT_UNKNOWN, COMPLETION_FORMAT_ZSH, OPT_COMPLETION_SHELL_BASH, OPT_COMPLETION_SHELL_FISH, OPT_COMPLETION_SHELL_POWERSHELL, OPT_COMPLETION_SHELL_ZSH, and OPTIONS_COMPLETIONS_LOWER_BUFFER_SIZE.

Referenced by action_completions().