feat hectic C: logger log in file

package/c/hectic/docs/file_logging.md

@@ -0,0 +1,132 @@
+# File Logging in Hectic Library
+
+This document covers the file logging functionality in the Hectic library, including its configuration and usage in different scenarios.
+
+## Overview
+
+Hectic's logging system now supports logging to files, offering three output modes:
+1. Stderr only (default)
+2. File only
+3. Both stderr and file
+
+This gives you flexibility to route logs where they're most needed while maintaining the same structured logging interface.
+
+## Configuration Methods
+
+### 1. Environment Variables
+
+Configure logging with environment variables:
+
+```sh
+# Set log file path
+export LOG_FILE=/path/to/your/logfile.log
+
+# Set output mode (STDERR_ONLY, FILE_ONLY, BOTH)
+export LOG_OUTPUT_MODE=BOTH
+
+# Set log level as usual
+export LOG_LEVEL=DEBUG
+
+# Run your application
+./your_program
+```
+
+### 2. Programmatic Configuration
+
+Configure logging in your code:
+
+```c
+#include "hectic.h"
+
+int main() {
+    // Initialize logger
+    logger_init();
+    
+    // Set log file (returns 0 on success, -1 on failure)
+    if (logger_set_file("/path/to/logfile.log") != 0) {
+        raise_exception("Failed to open log file");
+        return 1;
+    }
+    
+    // Set output mode
+    logger_set_output_mode(LOG_OUTPUT_BOTH);
+    
+    // Your application code here
+    raise_info("Application started");
+    
+    // Clean up on exit
+    logger_free();
+    
+    return 0;
+}
+```
+
+## Output Modes
+
+### `LOG_OUTPUT_STDERR_ONLY` (Default)
+- All log messages go to stderr only
+- No file output even if a log file is set
+
+### `LOG_OUTPUT_FILE_ONLY`
+- All log messages go to the log file only
+- Nothing is printed to stderr (useful for daemon processes)
+- ANSI color codes are automatically stripped from file output
+
+### `LOG_OUTPUT_BOTH`
+- All log messages go to both stderr and the log file
+- ANSI colors appear on stderr but are stripped from file output
+
+## File Handling Details
+
+- Log files are opened in append mode
+- The library automatically flushes after each log message to ensure logs are written immediately
+- ANSI color codes are automatically stripped from file output to avoid cluttering log files with escape sequences
+- If a file cannot be opened, an error message is printed to stderr
+
+## API Reference
+
+### Setting the Log File
+
+```c
+int logger_set_file(const char *file_path);
+```
+
+- **Parameters**: `file_path` - Path to the log file, or NULL to disable file logging
+- **Returns**: 0 on success, -1 on failure (e.g., unable to open file)
+- **Notes**: 
+  - Automatically closes any previously opened log file
+  - Opens the new file in append mode
+  - If NULL is passed, disables file logging and resets output mode to stderr only
+
+### Setting the Output Mode
+
+```c
+void logger_set_output_mode(LogOutputMode mode);
+```
+
+- **Parameters**: `mode` - One of `LOG_OUTPUT_STDERR_ONLY`, `LOG_OUTPUT_FILE_ONLY`, or `LOG_OUTPUT_BOTH`
+- **Notes**: 
+  - Has no effect if file logging is not configured and mode is file-related
+  - Does not check if the log file is successfully opened
+
+## Example
+
+See `examples/file_logging_example.c` for a complete working example of file logging.
+
+## Best Practices
+
+1. **Always check the return value of `logger_set_file()`**:
+   ```c
+   if (logger_set_file("/path/to/logfile.log") != 0) {
+       // Handle error
+   }
+   ```
+
+2. **Use appropriate output modes**:
+   - For interactive CLI applications: `LOG_OUTPUT_STDERR_ONLY` or `LOG_OUTPUT_BOTH`
+   - For daemon/service applications: `LOG_OUTPUT_FILE_ONLY`
+   - For debugging sessions: `LOG_OUTPUT_BOTH`
+
+3. **Consider log rotation**: The library doesn't handle log rotation, so for long-running applications, consider external log rotation solutions.
+
+4. **Close properly**: Always call `logger_free()` to ensure log files are properly closed.