builder.h

Go to the documentation of this file.

 
#pragma once
 
#include <stdbool.h>
#include <stddef.h>
#include <stdio.h>
#include "../common.h"
#include "../options/options.h" // For option_mode_bitmask_t

typedef enum {
  OPTION_TYPE_BOOL,     
  OPTION_TYPE_INT,      
  OPTION_TYPE_STRING,   
  OPTION_TYPE_DOUBLE,   
  OPTION_TYPE_CALLBACK, 
  OPTION_TYPE_ACTION    
} option_type_t;

typedef enum {
  OPTION_INPUT_NONE,     
  OPTION_INPUT_ENUM,     
  OPTION_INPUT_NUMERIC,  
  OPTION_INPUT_STRING,   
  OPTION_INPUT_FILEPATH, 
  OPTION_INPUT_CHOICE    
} option_input_type_t;

typedef struct {
  // Enum values with descriptions (null-terminated arrays)
  const char *
      *enum_values; 
  const char *
      *enum_descriptions; 
  const int *enum_integer_values; 
 
  // Numeric range
  struct {
    int min;  
    int max;  
    int step; 
  } numeric_range;
 
  // Examples (must be null-terminated)
  const char **examples; 
 
  // Default value (informational, may be duplicated from descriptor)
  const char *default_value; 
 
  // Input type for completions
  option_input_type_t input_type; 
 
  // Flags
  bool is_list; 
 
  // Validation pattern (optional)
  const char *validation_pattern; 
} option_metadata_t;

typedef enum {
  DEPENDENCY_REQUIRES,  
  DEPENDENCY_CONFLICTS, 
  DEPENDENCY_IMPLIES    
} dependency_type_t;

typedef struct {
  // Identification
  const char *long_name; 
  char short_name;       
 
  // Type and storage
  option_type_t type; 
  size_t offset;      
 
  // Documentation
  const char *help_text;       
  const char *group;           
  const char *arg_placeholder; 
  bool hide_from_mode_help;    
  bool hide_from_binary_help;  
 
  // Default and validation
  const void *default_value; 
  bool required;             
  const char *env_var_name;  
 
  // Validation receives the full options struct and uses SET_ERRNO() on failure.
  bool (*validate)(const void *options_struct);
 
  // Custom parsing (for OPTION_TYPE_CALLBACK)
  bool (*parse_fn)(const char *arg, void *dest, char **error_msg);
 
  // Action callback (for OPTION_TYPE_ACTION)
  void (*action_fn)(void); 
 
  // Memory management
  bool owns_memory; 
 
  // Optional argument support (for OPTION_TYPE_CALLBACK)
  bool optional_arg; 
 
  // Mode applicability
  option_mode_bitmask_t mode_bitmask; 
 
  // Completion metadata (NEW - for smart shell completions)
  option_metadata_t metadata; 
 
  // Mode-aware default getter (for options with mode-specific defaults)
  const void *(*mode_default_getter)(
      asciichat_mode_t mode); 
} option_descriptor_t;

typedef struct {
  const char *mode;        
  const char *positional;  
  bool show_options;       
  const char *description; 
} usage_descriptor_t;

typedef struct {
  uint32_t mode_bitmask; 
  const char *args;      
  const char *description;
  bool owns_args_memory;   
  bool is_utility_command; 
} example_descriptor_t;

typedef struct {
  const char *name;        
  const char *description; 
} help_mode_descriptor_t;

typedef struct {
  const char *option_name;   
  dependency_type_t type;    
  const char *depends_on;    
  const char *error_message; 
} option_dependency_t;

typedef struct {
  const char *name;      
  const char *help_text; 
  bool required;         
 
  // Programmatic help examples
  const char *section_heading; 
  const char **examples;       
  size_t num_examples;         

  int (*parse_fn)(const char *arg, void *config, char **remaining, int num_remaining, char **error_msg);
 
  // Mode applicability
  option_mode_bitmask_t mode_bitmask; 
} positional_arg_descriptor_t;

typedef struct {
  const char *heading;                
  const char *content;                
  option_mode_bitmask_t mode_bitmask; 
} custom_section_descriptor_t;

typedef struct {
  option_descriptor_t *descriptors; 
  size_t num_descriptors;           
 
  option_dependency_t *dependencies; 
  size_t num_dependencies;           
 
  positional_arg_descriptor_t *positional_args; 
  size_t num_positional_args;                   
 
  size_t struct_size;       
  const char *program_name; 
  const char *description;  
 
  // Programmatic help generation metadata
  usage_descriptor_t *usage_lines; 
  size_t num_usage_lines;          
 
  example_descriptor_t *examples; 
  size_t num_examples;            
 
  help_mode_descriptor_t *modes; 
  size_t num_modes;              
 
  custom_section_descriptor_t *custom_sections; 
  size_t num_custom_sections;                   
 
  // Memory management (internal use)
  char **owned_strings;          
  size_t num_owned_strings;      
  size_t owned_strings_capacity; 
} options_config_t;

typedef struct {
  option_descriptor_t *descriptors; 
  size_t num_descriptors;           
  size_t descriptor_capacity;       
 
  option_dependency_t *dependencies; 
  size_t num_dependencies;           
  size_t dependency_capacity;        
 
  positional_arg_descriptor_t *positional_args; 
  size_t num_positional_args;                   
  size_t positional_arg_capacity;               
 
  usage_descriptor_t *usage_lines; 
  size_t num_usage_lines;          
  size_t usage_line_capacity;      
 
  example_descriptor_t *examples; 
  size_t num_examples;            
  size_t example_capacity;        
 
  help_mode_descriptor_t *modes; 
  size_t num_modes;              
  size_t mode_capacity;          
 
  custom_section_descriptor_t *custom_sections; 
  size_t num_custom_sections;                   
  size_t custom_section_capacity;               
 
  size_t struct_size;
  const char *program_name;
  const char *description;
 
  // Track dynamically allocated strings owned by the builder, to be transferred to config
  char **owned_strings_builder;
  size_t num_owned_strings_builder;
  size_t owned_strings_builder_capacity;
} options_builder_t;
 
// ============================================================================
// Builder Lifecycle
// ============================================================================

options_builder_t *options_builder_create(size_t struct_size);

options_builder_t *options_builder_from_preset(const options_config_t *preset);

void options_builder_destroy(options_builder_t *builder);

options_config_t *options_builder_build(options_builder_t *builder);

void options_config_destroy(options_config_t *config);
 
// ============================================================================
// Adding Options
// ============================================================================

void options_builder_add_bool(options_builder_t *builder, const char *long_name, char short_name, size_t offset,
                              bool default_value, const char *help_text, const char *group, bool required,
                              const char *env_var_name);

void options_builder_add_int(options_builder_t *builder, const char *long_name, char short_name, size_t offset,
                             int default_value, const char *help_text, const char *group, bool required,
                             const char *env_var_name, bool (*validate)(const void *options_struct));

void options_builder_add_int_with_metadata(options_builder_t *builder, const char *long_name, char short_name,
                                           size_t offset, int default_value, const char *help_text, const char *group,
                                           bool required, const char *env_var_name,
                                           bool (*validate)(const void *options_struct),
                                           const option_metadata_t *metadata);

void options_builder_add_string(options_builder_t *builder, const char *long_name, char short_name, size_t offset,
                                const char *default_value, const char *help_text, const char *group, bool required,
                                const char *env_var_name, bool (*validate)(const void *options_struct));

void options_builder_add_double(options_builder_t *builder, const char *long_name, char short_name, size_t offset,
                                double default_value, const char *help_text, const char *group, bool required,
                                const char *env_var_name, bool (*validate)(const void *options_struct),
                                bool optional_arg);
 
void options_builder_add_double_with_metadata(options_builder_t *builder, const char *long_name, char short_name,
                                              size_t offset, double default_value, const char *help_text,
                                              const char *group, bool required, const char *env_var_name,
                                              bool (*validate)(const void *options_struct),
                                              const option_metadata_t *metadata, bool optional_arg);

void options_builder_add_callback(options_builder_t *builder, const char *long_name, char short_name, size_t offset,
                                  const void *default_value, size_t value_size,
                                  bool (*parse_fn)(const char *arg, void *dest, char **error_msg),
                                  const char *help_text, const char *group, bool required, const char *env_var_name);

void options_builder_add_callback_optional(options_builder_t *builder, const char *long_name, char short_name,
                                           size_t offset, const void *default_value, size_t value_size,
                                           bool (*parse_fn)(const char *arg, void *dest, char **error_msg),
                                           const char *help_text, const char *group, bool required,
                                           const char *env_var_name, bool optional_arg);

void options_builder_add_callback_with_metadata(options_builder_t *builder, const char *long_name, char short_name,
                                                size_t offset, const void *default_value, size_t value_size,
                                                bool (*parse_fn)(const char *arg, void *dest, char **error_msg),
                                                const char *help_text, const char *group, bool required,
                                                const char *env_var_name, bool optional_arg,
                                                const option_metadata_t *metadata);

void options_builder_add_action(options_builder_t *builder, const char *long_name, char short_name,
                                void (*action_fn)(void), const char *help_text, const char *group);

void options_builder_set_mode_bitmask(options_builder_t *builder, option_mode_bitmask_t mode_bitmask);

void options_builder_set_arg_placeholder(options_builder_t *builder, const char *arg_placeholder);
 
// ============================================================================
// Completion Metadata (NEW - Phase 2)
// ============================================================================

void options_builder_set_enum_values(options_builder_t *builder, const char *option_name, const char **values,
                                     const char **descriptions);

void options_builder_set_numeric_range(options_builder_t *builder, const char *option_name, int min, int max, int step);

void options_builder_set_examples(options_builder_t *builder, const char *option_name, const char **examples);

void options_builder_set_input_type(options_builder_t *builder, const char *option_name,
                                    option_input_type_t input_type);

void options_builder_mark_as_list(options_builder_t *builder, const char *option_name);

void options_builder_set_default_value_display(options_builder_t *builder, const char *option_name,
                                               const char *default_value);

void options_builder_add_descriptor(options_builder_t *builder, const option_descriptor_t *descriptor);
 
// ============================================================================
// Managing Dependencies
// ============================================================================

void options_builder_add_dependency_requires(options_builder_t *builder, const char *option_name,
                                             const char *depends_on, const char *error_message);

void options_builder_add_dependency_conflicts(options_builder_t *builder, const char *option_name,
                                              const char *conflicts_with, const char *error_message);

void options_builder_add_dependency_implies(options_builder_t *builder, const char *option_name, const char *implies,
                                            const char *error_message);

void options_builder_add_dependency(options_builder_t *builder, const option_dependency_t *dependency);

void options_builder_mark_binary_only(options_builder_t *builder, const char *option_name);
 
// ============================================================================
// Positional Arguments
// ============================================================================

void options_builder_add_positional(options_builder_t *builder, const char *name, const char *help_text, bool required,
                                    const char *section_heading, const char **examples, size_t num_examples,
                                    option_mode_bitmask_t mode_bitmask,
                                    int (*parse_fn)(const char *arg, void *config, char **remaining, int num_remaining,
                                                    char **error_msg));

asciichat_error_t options_config_parse_positional(const options_config_t *config, int remaining_argc,
                                                  char **remaining_argv, void *options_struct);
 
// ============================================================================
// Programmatic Help Generation
// ============================================================================

void options_builder_add_usage(options_builder_t *builder, const char *mode, const char *positional, bool show_options,
                               const char *description);

void options_builder_add_example(options_builder_t *builder, uint32_t mode_bitmask, const char *args,
                                 const char *description, bool owns_args);

void options_builder_add_example_utility(options_builder_t *builder, uint32_t mode_bitmask, const char *args,
                                         const char *description, bool is_utility_command);

void options_builder_add_mode(options_builder_t *builder, const char *name, const char *description);

void options_builder_add_custom_section(options_builder_t *builder, const char *heading, const char *content,
                                        option_mode_bitmask_t mode_bitmask);
 
// ============================================================================
// Preset Configurations
// ============================================================================

options_config_t *options_preset_unified(const char *program_name, const char *description);
 
// ============================================================================
// Parsing and Validation
// ============================================================================

asciichat_error_t options_config_set_defaults(const options_config_t *config, void *options_struct);

asciichat_error_t options_config_parse(const options_config_t *config, int argc, char **argv, void *options_struct,
                                       option_mode_bitmask_t detected_mode, int *remaining_argc,
                                       char ***remaining_argv);

asciichat_error_t options_config_validate(const options_config_t *config, const void *options_struct,
                                          char **error_message);

int options_config_calculate_max_col_width(const options_config_t *config);

void options_config_print_usage(const options_config_t *config, FILE *stream);

void options_config_print_usage_section(const options_config_t *config, FILE *stream);

void options_config_print_options_sections_with_width(const options_config_t *config, FILE *stream, int max_col_width,
                                                      asciichat_mode_t mode);

void options_config_print_options_sections(const options_config_t *config, FILE *stream, asciichat_mode_t mode);

void options_print_help_for_mode(const options_config_t *config, asciichat_mode_t mode, const char *program_name,
                                 const char *description, FILE *desc);

void options_struct_destroy(const options_config_t *config, void *options_struct);
 
// ============================================================================
// Option Formatting Utilities
// ============================================================================

const char *options_get_type_placeholder(option_type_t type);

int options_format_default_value(option_type_t type, const void *default_value, char *buf, size_t bufsize);
 
// ============================================================================
// Typo Suggestions for Unknown Options
// ============================================================================

const char *find_similar_option_with_mode(const char *unknown_opt, const options_config_t *config,
                                          option_mode_bitmask_t current_mode_bitmask);

void options_builder_set_string_parser(options_builder_t *builder, bool (*parser)(const char *, void *, char **));