filecomplete/filecomplete.h

#ifndef FILE_COMPLETE_H
#define FILE_COMPLETE_H

/**
 * @file file_complete.h
 * @brief 控制台读取用户输入时，文件自动补全功能
 *
 * 编码说明：
 * - 如果程序运行环境使用 GBK 编码，请手动定义宏 `BINARY_GBK`。
 * - 默认编码为 UTF-8。
 *
 * 功能说明：
 * - 支持添加截止符号以确定路径补全范围。
 * - 提供替代 `std::getline` 的用户输入读取函数。
 * - 提供控制台光标控制与线程安全打印机制。
 */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 设置路径补全的截止符号。
 *
 * @param deadline_ch 截止符号（例如 '|'）。
 */
void fc_append(char deadline_ch);

/**
 * @brief 设置补全提示的前缀显示内容。
 *
 * @param header 要显示的前缀字符串。
 */
void fc_set_header(const char* h);

/**
 * @brief 读取用户输入，替代 `std::getline`。
 *
 * @return 成功返回堆分配的字符串，需使用 `fc_free` 释放；
 *         如果返回 `NULL`，表示检测到终止命令（如 Ctrl+C）。
 */
char* fc_readline(void);

/**
 * @brief 启用控制台光标显示。
 */
void fc_enable_cur(void);

/**
 * @brief 禁用控制台光标显示。
 */
void fc_disable_cur(void);

/**
 * @brief 锁定打印，确保多线程环境下的打印顺序一致。
 */
void fc_lock_print(void);

/**
 * @brief 解锁打印，允许其他线程继续输出。
 */
void fc_unlock_print(void);

/**
 * @brief 释放 `fc_readline` 返回的字符串内存。
 *
 * @param str 需要释放的字符串指针。
 */
void fc_free(char* str);

/**
 * @brief 开启特殊字符替换，如 ~ 回车后会替换为家目录路径。
 */
void fc_turn_on();

/**
 * @brief 关闭殊字符替换
 */
void fc_turn_off();

#ifdef __cplusplus
}
#endif

#endif /* FILE_COMPLETE_H */