### Example XDG_RUNTIME_DIR Environment Variable

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Shows an example of setting the XDG_RUNTIME_DIR environment variable, which serves as the base directory for socket creation.

```bash
XDG_RUNTIME_DIR=/run/user/1000
```

--------------------------------

### Example XDG_CURRENT_DESKTOP Environment Variable

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Provides an example of setting the XDG_CURRENT_DESKTOP environment variable, used for logging the current desktop environment.

```bash
XDG_CURRENT_DESKTOP=KDE
```

--------------------------------

### Bash netcat Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Demonstrates how to get current gamma and temperature values and then adjust them using netcat to communicate with the Hyprsunset socket.

```bash
#!/bin/bash
SOCKET="/run/user/$(id -u)/hypr/0/.hyprsunset.sock"

# Get current values
gamma=$(echo "gamma" | nc -U "$SOCKET")
temp=$(echo "temperature" | nc -U "$SOCKET")

echo "Current: ${gamma}% gamma, ${temp}K temperature"

# Adjust
echo "gamma +10" | nc -U "$SOCKET"
echo "temperature -500" | nc -U "$SOCKET"
```

--------------------------------

### Hyprsunset Configuration File Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/README.md

Example configuration file for Hyprsunset, defining maximum gamma and multiple time-based color profiles with their respective temperature, gamma, and identity settings.

```ini
max-gamma = 150

profile {
    time = 06:00
    temperature = 5500
    gamma = 1.0
    identity = 0
}

profile {
    time = 18:00
    temperature = 3500
    gamma = 0.9
    identity = 0
}

profile {
    time = 23:00
    temperature = 2700
    gamma = 0.8
    identity = 0
}
```

--------------------------------

### Enable and Start Hyprsunset systemd Service

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Commands to enable the Hyprsunset systemd user service to start on login and to start it immediately.

```bash
systemctl --user enable hyprsunset.service
systemctl --user start hyprsunset.service
```

--------------------------------

### Startup Logging Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/Debug.md

Logs initial messages during application startup, including version information and specific warnings if arguments are missing.

```cpp
// main.cpp
Debug::log(NONE, "─ hyprsunset v{} ──
│", HYPRSUNSET_VERSION);
```

```cpp
Debug::log(NONE, "✖ No temperature provided for {}", argv[i]);
```

--------------------------------

### Verbose Logging Output Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

This example shows the typical output when verbose logging is enabled, including socket status and connection messages.

```text
[LOG] hyprsunset socket started at /run/user/1000/hypr/0/.hyprsunset.sock
[TRACE] [core] got poll event
[LOG] Accepted incoming socket connection request
```

--------------------------------

### Example Sunset Profiles

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Example configuration showcasing multiple profiles for different times of day, including morning, midday, evening, and night settings. The 'identity' key can be used to disable color change.

```hyprlang
profile {
    time = 06:00
    temperature = 6500   # Morning: neutral white
    gamma = 1.0
    identity = 0
}

profile {
    time = 12:00
    temperature = 5500   # Midday: still neutral
    gamma = 1.0
    identity = 0
}

profile {
    time = 18:00
    temperature = 4000   # Evening: warm
    gamma = 1.0
    identity = 0
}

profile {
    time = 21:00
    temperature = 3000   # Night: very warm
    gamma = 0.8          # Also 20% dimmer
    identity = 0
}

profile {
    time = 23:00
    temperature = 6000   # Late night: disable filter
    gamma = 1.0
    identity = 1         # No color change
}

```

--------------------------------

### Bash socat Examples

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Shows how to use socat for both interactive communication and one-shot command execution with the Hyprsunset socket.

```bash
#!/bin/bash
SOCKET="/run/user/$(id -u)/hypr/0/.hyprsunset.sock"

# Interactive mode
socat - UNIX-CONNECT:"$SOCKET"

# One-shot command
echo "profile" | socat - UNIX-CONNECT:"$SOCKET"
```

--------------------------------

### Example HYPRLAND_INSTANCE_SIGNATURE Environment Variable

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Demonstrates setting the HYPRLAND_INSTANCE_SIGNATURE environment variable, which is used to differentiate between multiple Hyprland instances.

```bash
HYPRLAND_INSTANCE_SIGNATURE=0
```

--------------------------------

### CConfigManager Constructor Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CConfigManager.md

Demonstrates how to instantiate CConfigManager, either by auto-detecting the configuration file path or by specifying an explicit path.

```cpp
// Auto-detect config location
auto configMgr = std::make_unique<CConfigManager>("");

// Or specify explicit path
auto configMgr = std::make_unique<CConfigManager>("/etc/hyprsunset/custom.conf");
```

--------------------------------

### C IPC Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

A C program demonstrating how to connect to the Hyprsunset socket, send a command, and read the reply.

```c
#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <sys/socket.h>
#include <sys/un.h>

int main() {
    char *socket_path = "/run/user/1000/hypr/0/.hyprsunset.sock";
    int sock = socket(AF_UNIX, SOCK_STREAM, 0);
    
    struct sockaddr_un addr;
    memset(&addr, 0, sizeof(addr));
    addr.sun_family = AF_UNIX;
    strcpy(addr.sun_path, socket_path);
    
    connect(sock, (struct sockaddr *)&addr, sizeof(addr));
    
    // Send command
    char cmd[] = "gamma +10\0";
    write(sock, cmd, strlen(cmd) + 1);
    
    // Read reply
    char reply[256];
    read(sock, reply, sizeof(reply));
    printf("Reply: %s\n", reply);
    
    close(sock);
    return 0;
}
```

--------------------------------

### Hard-coded Socket Path

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Use this method for single-instance setups where the socket path is known beforehand.

```bash
/run/user/1000/hypr/0/.hyprsunset.sock
```

--------------------------------

### CHyprsunset::init()

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CHyprsunset.md

Initializes the Wayland connection, discovers outputs, and starts the event loop for CHyprsunset. Returns 1 on success and 0 on failure.

```APIDOC
## CHyprsunset::init()

### Description
Initializes Wayland connection, discovers outputs, and starts the event loop.

### Method
```cpp
int CHyprsunset::init();
```

### Parameters
None

### Return
`1` on success, `0` on failure

### Throws
None (returns 0 on error)

### Description Details
- Connects to Wayland display via `wl_display_connect(nullptr)`
- Gets registry and registers callbacks for interface discovery
- Binds to `hyprland-ctm-control-v1` protocol manager
- Enumerates outputs (`wl_output`) and stores them in `state.outputs`
- Loads configuration and current profile via `loadCurrentProfile()`
- Initializes IPC socket via `g_pIPCSocket->initialize()`
- Registers signal handlers for SIGTERM and SIGINT
- Creates timer FD for profile transitions
- Calls `schedule()` to start scheduler thread
- Calls `startEventLoop()` (blocks on main thread)

### Errors Handled
- Wayland display connection failure → logs error, returns 0
- Missing `hyprland-ctm-control-v1` support → logs error, returns 0
- CTM manager already running (protocol v2+) → logs error, exits with code 1 via callback

### Source
`src/Hyprsunset.cpp:101–173`

### Example
```cpp
auto app = std::make_unique<CHyprsunset>();
if (!app->init()) {
    std::cerr << "Initialization failed\n";
    return 1;
}
// init() blocks until terminate() is called
```
```

--------------------------------

### Test Hyprsunset IPC Commands

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/README.md

This script starts hyprsunset in the background, sends various IPC commands (gamma, temperature, profile, identity get) to its socket, and then terminates the application. It's useful for testing IPC functionality without manual interaction.

```bash
# Start in background
hyprsunset &
sleep 1

# Test commands
for cmd in "gamma" "temperature" "profile" "identity get"; do
    echo $cmd | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
done

# Stop
pkill hyprsunset
```

--------------------------------

### Example XDG_CONFIG_HOME Environment Variable

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Illustrates setting the XDG_CONFIG_HOME environment variable, which defines the base directory for Hyprsunset's configuration file search.

```bash
XDG_CONFIG_HOME=/etc/xdg
```

--------------------------------

### Example Hyprsunset Configuration File

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CConfigManager.md

Illustrates the structure and syntax of a typical hyprsunset configuration file, defining sunset profiles with time, temperature, gamma, and identity settings.

```hyprlang
max-gamma = 150

profile {
    time = 06:00
    temperature = 5000
    gamma = 1.0
    identity = 0
}

profile {
    time = 18:00
    temperature = 3500
    gamma = 0.9
    identity = 0
}

profile {
    time = 22:00
    temperature = 2700
    gamma = 0.8
    identity = 0
}
```

--------------------------------

### Wayland Connection Failure Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/errors.md

This example demonstrates the error output when Hyprsunset fails to connect to a Wayland compositor, typically occurring when run on an X11 session. The application exits with code 1.

```bash
$ hyprsunset  # Running on X11
✖ Couldn't connect to a wayland compositor
$ exit 1
```

--------------------------------

### Python IPC Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

A Python script to send commands to the Hyprsunset socket, retrieve current settings, and set new values.

```python
import socket
import sys
import os

socket_path = f"/run/user/{os.getuid()}/hypr/0/.hyprsunset.sock"

def send_command(cmd):
    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    sock.connect(socket_path)
    sock.sendall(cmd.encode())
    response = sock.recv(1024).decode()
    sock.close()
    return response

print(send_command("gamma"))  # Get gamma
print(send_command("gamma 80"))  # Set gamma
```

--------------------------------

### Invalid Time Format in Profile Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/errors.md

Shows examples of malformed 'time' fields in a profile, which can occur due to missing separators, non-numeric values, or out-of-range hours/minutes. The affected profile is skipped.

```log
[ERR] Invalid time format: 25:80, skipping profile 0
[ERR] Invalid time format: nottime, skipping profile 1
```

--------------------------------

### Display Version and Exit

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Print the application's version string and exit immediately by using the `--version` or `-v` flag. This is a standard option for checking the installed version.

```bash
$ hyprsunset --version
hyprsunset v0.3.3
```

--------------------------------

### Invalid Command-Line Temperature Range Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Shows the error output for a temperature value outside the acceptable range.

```bash
$ hyprsunset --temperature 500
✖ Temperature 500 is not valid (calculateMatrix will fail)
exit code: 1
```

--------------------------------

### Hyprsunset Netcat Examples

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CIPCSocket.md

Use netcat to send commands to the Hyprsunset IPC socket for querying or setting gamma and temperature, or to check the current profile.

```bash
# Get current gamma
echo "gamma" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock

# Set gamma to 60%
echo "gamma 60" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock

# Increase temperature by 500K
echo "temperature +500" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock

# Query current profile
echo "profile" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
```

--------------------------------

### SSunsetProfile Example Usage

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/types.md

Illustrates how to create SSunsetProfile instances for different times of day, specifying color temperature and gamma. The 'identity' flag can be used to disable color changes.

```cpp
SSunsetProfile morning {
    .time = {.hour = std::chrono::hours(6), .minute = std::chrono::minutes(0)},
    .temperature = 5500,
    .gamma = 1.0f,
    .identity = false
};

SSunsetProfile evening {
    .time = {.hour = std::chrono::hours(18), .minute = std::chrono::minutes(0)},
    .temperature = 3500,
    .gamma = 0.9f,
    .identity = false
};

SSunsetProfile disabled {
    .time = {.hour = std::chrono::hours(23), .minute = std::chrono::minutes(0)},
    .temperature = 6000,
    .gamma = 1.0f,
    .identity = true  // No color change at night
};
```

--------------------------------

### Initialize CHyprsunset Application

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CHyprsunset.md

Initializes the Wayland connection, discovers outputs, and starts the event loop. This method blocks until terminate() is called. Ensure proper error handling for initialization failures.

```cpp
auto app = std::make_unique<CHyprsunset>();
if (!app->init()) {
    std::cerr << "Initialization failed\n";
    return 1;
}
// init() blocks until terminate() is called
```

--------------------------------

### Log Message Examples

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/Debug.md

Demonstrates various ways to use the Debug::log() function with different log levels and format specifiers, including default, zero-padded, and hexadecimal formatting.

```cpp
Debug::log(NONE, "┣ Setting temperature to {}K", 3500);
// Output: ┣ Setting temperature to 3500K

Debug::log(LOG, "Found {} outputs", state.outputs.size());
// Output (if trace=true): [LOG] Found 2 outputs
// Output (if trace=false): (suppressed)

Debug::log(ERR, "Invalid temperature: {} (range: {}-{})", temp, 1000, 20000);
// Output: [ERR] Invalid temperature: 500 (range: 1000-20000)

Debug::log(NONE, "Time: {:0>2}:{:0>2}", hours, minutes);
// Output: Time: 08:30
```

--------------------------------

### Configuration Parse Error Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/errors.md

Illustrates a syntax error detected by the Hyprlang parser in the configuration file. The application attempts to proceed by ignoring faulty entries.

```log
[ERR] Config has errors:
Line 5: Unexpected token '{'
Proceeding ignoring faulty entries
```

--------------------------------

### RASSERT() Assertion Examples

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/Debug.md

Illustrates the usage of the RASSERT macro for validating conditions and handling potential errors, including a case with exception handling for configuration value retrieval.

```cpp
RASSERT(state.pCTMMgr != nullptr, "CTM manager is null");
// If pCTMMgr is null, prints and aborts

RASSERT(version >= 2, "Protocol version {} is too old", version);
// If version < 2, prints assertion failure with version value

// In CConfigManager::getMaxGamma():
try {
    return std::any_cast<Hyprlang::INT>(m_config.getConfigValue("max-gamma")) / 100.f;
} catch (const std::bad_any_cast& e) {
    RASSERT(false, "Failed to construct max-gamma: {}", e.what());
    // Always aborts (catch block means config parsing succeeded but value is wrong type)
}
```

--------------------------------

### Parse Profile Details Reply

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Example of how to parse the multi-line output from the 'profile' command to extract specific details like time and temperature using standard shell utilities.

```bash
result=$(echo "profile" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock)
time=$(echo "$result" | grep "^Time:" | cut -d' ' -f2)
temp=$(echo "$result" | grep "^Temperature:" | cut -d' ' -f2)
```

--------------------------------

### Invalid Command-Line Argument Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Demonstrates an error message when an invalid value is provided for the --temperature argument.

```bash
$ hyprsunset --temperature abc
✖ Temperature abc is not valid
exit code: 1
```

--------------------------------

### IPC Logging Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/Debug.md

Logs messages related to Inter-Process Communication (IPC) socket operations, including startup, connection acceptance, and received requests.

```cpp
// IPCSocket.cpp
Debug::log(LOG, "hyprsunset socket started at {} (fd: {})", socketPath, SOCKET);
```

```cpp
Debug::log(LOG, "Accepted incoming socket connection request on fd {}", ACCEPTEDCONNECTION);
```

```cpp
Debug::log(LOG, "Received a request: {}", copy);
```

--------------------------------

### Hyprsunset Socat Script Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CIPCSocket.md

A bash script utilizing socat to send a temperature command to the Hyprsunset IPC socket, taking the temperature value as an argument.

```bash
#!/bin/bash
SOCKET="/run/user/1000/hypr/0/.hyprsunset.sock"
echo "temperature $1" | socat - UNIX-CONNECT:$SOCKET
```

--------------------------------

### Event Loop Synchronization Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/types.md

Illustrates the usage of mutexes and condition variables for inter-thread communication within the Hyprsunset event loop. Used for scheduling profile transitions and processing events.

```cpp
// Scheduler thread:
std::lock_guard<std::mutex> lg(m_sEventLoopInternals.loopRequestMutex);
KELVIN = newProfile.temperature;
m_sEventLoopInternals.loopSignal.notify_all();

// Event loop:
std::unique_lock<std::mutex> lk(m_sEventLoopInternals.loopMutex);
m_sEventLoopInternals.loopSignal.wait_for(lk, std::chrono::milliseconds(5000), ...);
```

--------------------------------

### profile — Get Current Profile Details

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Queries the currently active profile configuration, returning details such as time, temperature, gamma, and identity status.

```APIDOC
## profile — Get Current Profile Details

### Description
Queries the currently active profile configuration, returning details such as time, temperature, gamma, and identity status. This is a read-only query.

### Syntax
```
profile
```

### Parameters
None

### Return Value
- Success: Returns multi-line profile details in the following format:
  ```
  Time: HH:MM
  Temperature: NNNN
  Gamma: N.NN
  Identity: true/false
  ```
- Error: Returns an error message string if no profile is loaded.

### Validation
- This is a read-only query and has no specific validation beyond checking if a profile is loaded.
- The command fails if no profile is currently loaded.

### Examples
```bash
echo "profile" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output:
# Time: 18:00
# Temperature: 3500
# Gamma: 0.9
# Identity: false
```

### Parsing Reply
```bash
result=$(echo "profile" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock)
time=$(echo "$result" | grep "^Time:" | cut -d' ' -f2)
temp=$(echo "$result" | grep "^Temperature:" | cut -d' ' -f2)
```

### Side Effects
None (read-only query).
```

--------------------------------

### Query/Set Color Temperature

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Use this command to get or set the color temperature. Values are in Kelvin. Out-of-range values are clamped, and invalid inputs return an error.

```bash
# Get current temperature
echo "temperature" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "3500"
```

```bash
# Set to warm (sunset-like)
echo "temperature 3000" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "ok"
```

```bash
# Increase by 500K (cooler)
echo "temperature +500" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "ok"
```

```bash
# Decrease by 1000K (warmer)
echo "temperature -1000" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "ok"
```

```bash
# Try to exceed range
echo "temperature 500" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "Invalid temperature (should be an integer in range 1000-20000)"
```

--------------------------------

### Missing Profile Property Log Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/errors.md

Indicates a critical error where a required property (time, temperature, gamma, or identity) is missing from a profile. This results in an std::out_of_range exception and application abortion.

```log
[CRIT] Missing property for Profile: <property>
Assertion failed at line <N> in ConfigManager.cpp
```

--------------------------------

### Hyprsunset Startup Flow Overview

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Illustrates the sequence of operations during Hyprsunset's startup, from argument parsing to event loop initialization.

```text
main()
  ├─ Parse command-line arguments
  │  ├─ temperature → g_pHyprsunset->KELVIN
  │  ├─ gamma → g_pHyprsunset->GAMMA
  │  ├─ gamma_max → g_pHyprsunset->MAX_GAMMA
  │  └─ identity → g_pHyprsunset->identity
  │
  ├─ Create CConfigManager
  │  └─ Searches for config file in XDG paths
  │
  ├─ CConfigManager::init()
  │  ├─ Register config schema
  │  └─ Parse config file
  │
  ├─ CHyprsunset::loadCurrentProfile()
  │  ├─ Get profiles from CConfigManager
  │  ├─ Get MAX_GAMMA from CConfigManager
  │  ├─ Find current profile by time
  │  ├─ Apply KELVIN, GAMMA, identity from profile
  │  └─ (Command-line args override if set)
  │
  ├─ CHyprsunset::calculateMatrix()
  │  ├─ Validate KELVIN and GAMMA
  │  └─ Compute 3×3 color matrix
  │
  └─ CHyprsunset::init()
     ├─ Connect to Wayland
     ├─ Enumerate outputs
     ├─ Initialize IPC socket
     └─ Start event loop
```

--------------------------------

### Setting up Poll File Descriptors for Event Loop

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/algorithm-reference.md

This C++ snippet defines the file descriptors for polling Wayland events and timer events. It's a crucial part of Hyprsunset's event loop setup, enabling asynchronous handling of Wayland and internal timers.

```cpp
pollfd pollfds[] = {
    {.fd = wl_display_get_fd(state.wlDisplay), .events = POLLIN},
    {.fd = state.timerFD, .events = POLLIN}
};
```

--------------------------------

### Display Help Information

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Use the --help or -h flag to print usage information and exit. This displays available options and their descriptions.

```bash
$ hyprsunset --help
┣ --gamma             -g  →  Set the display gamma (default 100%)
┣ --gamma_max             →  Set the maximum display gamma (default 100%, maximum 200%)
┣ --temperature       -t  →  Set the temperature in K (default 6000)
┣ --identity          -i  →  Use the identity matrix (no color change)
┣ --verbose               →  Print more logging
┣ --version           -v  →  Print the version
┣ --help              -h  →  Print this info
╹

```

--------------------------------

### Missing Configuration File Handling

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Illustrates the behavior when no configuration file is found; defaults are used, and profiles remain empty.

```bash
# No config found → uses defaults
g_pConfigManager = CConfigManager("")  // Searches XDG paths, not found
// Continues with default profiles = empty
```

--------------------------------

### Compile-time Format String Error Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/Debug.md

This example demonstrates a compile-time error that occurs when a float is passed to a format specifier expecting an integer (:d). Invalid format strings are caught during compilation.

```cpp
Debug::log(NONE, "Temperature: {:d}", 3500.5);  // Error: float to :d specifier
```

--------------------------------

### init()

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CConfigManager.md

Registers config keys and categories, then parses the configuration file. It handles potential parsing errors internally.

```APIDOC
## init()

### Description
Registers configuration keys and categories, including `max-gamma` and `profile` blocks with their respective settings. It then parses the configuration file, logging any errors encountered without throwing exceptions.

### Method
`void CConfigManager::init()`

### Parameters
None

### Return
`void`

### Description
1. Registers `max-gamma` (INTEGER, default 100).
2. Registers the `profile` category for anonymous profile blocks.
3. Registers required keys within each profile: `time` (STRING), `temperature` (INTEGER), `gamma` (FLOAT), `identity` (INTEGER).
4. Calls `m_config.commence()` and `m_config.parse()`.
5. Logs parse errors internally but does not throw.

### Example Configuration File
```
max-gamma = 150

profile {
    time = 06:00
    temperature = 5000
    gamma = 1.0
    identity = 0
}

profile {
    time = 18:00
    temperature = 3500
    gamma = 0.9
    identity = 0
}

profile {
    time = 22:00
    temperature = 2700
    gamma = 0.8
    identity = 0
}
```

### Error Handling
- If config file is missing or cannot be read, continues with defaults.
- If a parse error occurs, logs the error message but does not fail the application.
- Invalid profile values are skipped individually.
```

--------------------------------

### Missing Required Argument Value Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/errors.md

This example shows the error message when a command-line argument that requires a value, such as `--temperature`, is provided without one. The application exits with code 1.

```bash
$ hyprsunset --temperature
✖ No temperature provided for --temperature
exit 1
```

--------------------------------

### Invalid Temperature Argument Examples

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/errors.md

These examples show the error messages generated when the `--temperature` or `-t` argument is provided with an invalid value, either non-numeric or outside the acceptable range of 1000-20000K. The application exits with code 1.

```bash
$ hyprsunset --temperature abc
✖ Temperature abc is not valid
exit 1
```

```bash
$ hyprsunset --temperature 500
✖ Temperature invalid: 500. The temperature has to be between 1000 and 20000K
exit 1
```

--------------------------------

### Invalid Gamma Argument Examples

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/errors.md

These examples illustrate the error output when the `--gamma` or `-g` argument is supplied with an invalid value, such as non-numeric input or a value outside the allowed range (0% to MAX_GAMMA%). The application exits with code 1.

```bash
$ hyprsunset --gamma xyz
✖ Gamma xyz is not valid
exit 1
```

```bash
$ hyprsunset --gamma 150  # If MAX_GAMMA is 100%
✖ Gamma invalid: 150%. The gamma has to be between 0% and 100%
exit 1
```

--------------------------------

### Get Current Gamma

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CIPCSocket.md

Retrieves the current gamma setting. The value is returned as a percentage.

```bash
gamma
→ "80"  (returned as percentage)
```

--------------------------------

### Get Current Color Temperature

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CIPCSocket.md

Retrieves the current color temperature setting in Kelvin. The value is returned as an integer.

```bash
temperature
→ "3500"  (returned in Kelvin)
```

--------------------------------

### Get Current Gamma

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Query the current gamma adjustment level. Requires a Unix domain socket connection.

```bash
# Get current gamma
echo "gamma" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "80"
```

--------------------------------

### CIPCSocket::initialize

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CIPCSocket.md

Spawns a background thread to listen for and accept socket connections. This method sets up the Unix domain socket, binds it to a path derived from environment variables, and enters a loop to accept incoming client connections.

```APIDOC
## CIPCSocket::initialize

### Description
Spawns a background thread to listen for and accept socket connections. This method sets up the Unix domain socket, binds it to a path derived from environment variables, and enters a loop to accept incoming client connections.

### Method
`void initialize()`

### Parameters
None

### Return
`void`

### Throws
None

### Detailed Description
1. Spawns a detached thread that:
   - Creates a Unix domain socket (`AF_UNIX`, `SOCK_STREAM`)
   - Computes socket path from environment:
     - If `XDG_RUNTIME_DIR` is set: `$XDG_RUNTIME_DIR/hypr/<HYPRLAND_INSTANCE_SIGNATURE>/.hyprsunset.sock`
     - Otherwise: `/run/user/<UID>/hypr/.hyprsunset.sock`
   - Creates parent directory if needed (`$XDG_RUNTIME_DIR/hypr/` or `/run/user/<UID>/hypr/`)
   - Removes any stale socket file
   - Binds socket to the path
   - Listens with queue size 10
   - Enters accept loop to receive connections
   - For each accepted connection:
     - Reads command string (max 1024 bytes)
     - Acquires event loop request mutex
     - Sets `m_szRequest` and `m_bRequestReady = true`
     - Calls `g_pHyprsunset->tick()` to process the request
     - Waits for `m_bReplyReady = true` (busyloops with 1ms sleep)
     - Writes reply to socket
     - Resets `m_bReplyReady` and `m_szReply`

2. Thread is detached, runs until socket error or process exit

**Socket Path**:
- Depends on `HYPRLAND_INSTANCE_SIGNATURE` (set by Hyprland at startup)
- Multiple Hyprland instances have separate sockets
- Example: `/run/user/1000/hypr/0/hyprsunset.sock`

**Error Handling**:
- Socket creation failure → logs error, thread returns early, IPC disabled
- Bind failure → logs warning
- Listen/accept failure → logs error, thread exits
- Read/write errors → handled gracefully, connection closed

### Example
```cpp
auto ipcSocket = std::make_unique<CIPCSocket>();
ipcSocket->initialize();  // Spawns background thread

// Later, a client can connect:
// nc -U /run/user/1000/hypr/0/.hyprsunset.sock
```
```

--------------------------------

### Handle Reset Error: No Profile Loaded

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Demonstrates the error output when attempting to reset settings without a profile currently loaded. The command will return an error message indicating the issue.

```bash
# Error: no profile
echo "reset" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# (when no profile is loaded)
# Output: "No profile is currently loaded"
```

--------------------------------

### Get Current Local Time

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/algorithm-reference.md

Retrieves the current local time using std::chrono. This is a prerequisite for profile time matching.

```cpp
auto now = std::chrono::zoned_time(std::chrono::current_zone(), 
                                         std::chrono::system_clock::now())
                   .get_local_time();
```

--------------------------------

### Hyprsunset Command-Line Options

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/README.md

Use these options to control Hyprsunset's behavior when launching the application. Options include setting initial color temperature, gamma, identity mode, configuration file path, and verbosity.

```bash
hyprsunset [OPTIONS]

Options:
  -t, --temperature <K>   Set initial color temperature (1000–20000K)
  -g, --gamma <percent>   Set initial gamma (0–MAX_GAMMA%)
  --gamma_max <percent>   Set maximum gamma allowed (0–200%, default 100%)
  -i, --identity          Use identity matrix (no color change)
  -c, --config <path>     Use custom config file
  --verbose               Enable verbose logging
  -v, --version           Print version and exit
  -h, --help              Print help and exit
```

--------------------------------

### Specify Custom Configuration Path

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Provide a custom configuration file path using `--config` or `-c`. The application will use this file instead of the default locations. The file must be readable; missing files are tolerated.

```bash
hyprsunset --config /etc/hyprsunset/custom.conf
hyprsunset -c ~/.hyprsunset_alt.conf
```

--------------------------------

### Hyprsunset systemd Service File

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Configuration for a systemd user service to run Hyprsunset. This ensures Hyprsunset starts automatically with your graphical session and restarts on failure.

```ini
[Unit]
Description=Hyprsunset - Blue-light filter for Hyprland
After=graphical-session-pre.target
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/hyprsunset
Restart=on-failure

[Install]
WantedBy=graphical-session.target
```

--------------------------------

### Manual Directory Creation for Socket

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/errors.md

Use this command to manually create the necessary directory for the IPC socket if it fails to be created automatically. Ensure the UID matches your user ID.

```bash
mkdir -p /run/user/1000/hypr/
```

--------------------------------

### Profile Query Error Case

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CIPCSocket.md

Illustrates the error case when no profile is loaded in the configuration. An appropriate message is returned.

```bash
profile  (when no profiles in config)
→ "No profile is currently loaded"
```

--------------------------------

### Check Hyprland Version and CTM Manager Support

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/README.md

Verify your Hyprland version and check if a CTM (Color Temperature Manager) manager is available using hyprctl commands. This helps in understanding protocol compatibility.

```bash
hyprctl version
```

```bash
hyprctl clients | grep -i ctm
```

--------------------------------

### gamma

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Allows querying and setting the brightness (gamma) level of Hyprsunset. You can get the current gamma, set an absolute value, or adjust it relatively by increasing or decreasing.

```APIDOC
## gamma

### Description
Get or modify the brightness (gamma) level. This command can be used to query the current gamma, set an absolute gamma value, or increase/decrease the gamma by a specified amount.

### Method
N/A (Unix Domain Socket Command)

### Endpoint
N/A (Unix Domain Socket Command)

### Parameters
#### Command
- **gamma** (none) - Query current gamma as a percentage.
- **gamma <value>** (Integer or float) - Set gamma to N percentage. Range: 0–MAX_GAMMA.
- **gamma +<value>** (Integer or float) - Increase gamma by N percentage. Range: Unclamped.
- **gamma -<value>** (Integer or float) - Decrease gamma by N percentage. Range: Unclamped.

### Request Example
```bash
# Get current gamma
 echo "gamma" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock

# Set to 60%
 echo "gamma 60" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock

# Increase by 10%
 echo "gamma +10" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock

# Decrease by 5%
 echo "gamma -5" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
```

### Response
#### Success Response
- **Query**: "<percentage>" (e.g., "80" for 80%)
- **Set**: "ok"

#### Error Response
- Error message string (e.g., "Invalid gamma value (should be in range 0-100%)")

### Response Example
```json
// Query Success
"80"

// Set Success
"ok"

// Error Example
"Invalid gamma value (should be in range 0-100%)"
```
```

--------------------------------

### Mat3x3 Matrix Initialization and Multiplication

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/types.md

Demonstrates creating a 3x3 color transformation matrix and performing in-place multiplication. Useful for applying color adjustments like gamma correction.

```cpp
// From matrixForKelvin() in Hyprsunset.cpp
Mat3x3 matrix = std::array<float, 9>{
    r / 255.F, 0, 0,  // Red channel
    0, g / 255.F, 0,  // Green channel
    0, 0, b / 255.F   // Blue channel
};

// From Hyprsunset::calculateMatrix()
state.ctm = identity ? Mat3x3::identity() : matrixForKelvin(KELVIN);
state.ctm.multiply(std::array<float, 9>{GAMMA, 0, 0, 0, GAMMA, 0, 0, 0, GAMMA});
```

--------------------------------

### Hyprlang Configuration Value Aliases

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/types.md

Demonstrates how to add integer, string, and float configuration values using Hyprlang type aliases. Used for setting various profile parameters.

```cpp
m_config.addConfigValue("max-gamma", Hyprlang::INT{100});
m_config.addSpecialConfigValue("profile", "temperature", Hyprlang::INT{6000});
m_config.addSpecialConfigValue("profile", "gamma", Hyprlang::FLOAT{1.0f});
m_config.addSpecialConfigValue("profile", "time", Hyprlang::STRING{"00:00"});
```

--------------------------------

### Start Event Loop

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CHyprsunset.md

Runs the main event loop, which is a blocking operation. It spawns a poll thread to handle Wayland events and timer events, and processes them in a dispatch loop.

```cpp
void CHyprsunset::startEventLoop();
```

--------------------------------

### Configure Hyprsunset systemd Service with Custom Config

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Instructions to override the default systemd service configuration to use a custom Hyprsunset configuration file. This allows for specific settings at service startup.

```bash
systemctl --user edit hyprsunset.service
# Add:
# [Service]
# ExecStart=
# ExecStart=/usr/bin/hyprsunset --config /etc/hyprsunset/custom.conf
```

--------------------------------

### Command-line Arguments

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/MANIFEST.txt

Reference for all command-line arguments supported by Hyprsunset.

```APIDOC
## Command-line Arguments

### Description
Lists and describes the available command-line options for configuring Hyprsunset at startup.

### Arguments
- `--temperature` / `-t` (float): Set initial color temperature.
- `--gamma` / `-g` (float): Set initial gamma value.
- `--gamma_max` (float): Set the maximum allowed gamma value.
- `--config` / `-c` (path): Specify a custom configuration file path.
- `--verbose` / `-v`: Enable verbose logging.
- `--version` / `-V`: Display the Hyprsunset version.
- `--help` / `-h`: Show this help message and exit.
```

--------------------------------

### Query/Set Identity Matrix Mode

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Enable or disable the identity transformation to control color changes. Accepts 'true', 'false', or 'get'. Setting the mode triggers a reload, while querying does not.

```bash
# Enable (disable color changes)
echo "identity" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "ok"
```

```bash
echo "identity true" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "ok"
```

```bash
# Disable (resume color changes)
echo "identity false" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "ok"
```

```bash
# Query current state
echo "identity get" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "true" or "false"
```

--------------------------------

### Configuration File Parse Error Message

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Displays the error format for syntax errors encountered while parsing the configuration file.

```text
[ERR] Config has errors:
Line 15: Syntax error near '{'
Proceeding ignoring faulty entries
```

--------------------------------

### Reset All Settings to Profile

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CIPCSocket.md

Resets all Hyprsunset settings (temperature, gamma, identity) to match the currently loaded profile. A confirmation 'ok' is returned.

```bash
reset
→ "ok"  (loads current profile's temperature, gamma, identity)
```

--------------------------------

### Set Initial Gamma (Brightness)

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/configuration.md

Adjust the initial gamma (brightness multiplier) using `--gamma` or `-g`. Values are percentages; internally stored as a float. This setting does not persist across profile changes.

```bash
hyprsunset --gamma 80     # 20% dimmer
hyprsunset -g 120         # 20% brighter
hyprsunset --gamma 50     # 50% brightness (very dim)
```

--------------------------------

### max-gamma Type Mismatch Log Example

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/errors.md

Shows a critical error when the 'max-gamma' configuration value is not an integer, causing a std::bad_any_cast exception. The application aborts due to this malformed configuration.

```log
[CRIT] Failed to construct max-gamma: <cast error>
Assertion failed at line <N> in ConfigManager.cpp
```

--------------------------------

### Load Sunset Profiles and Max Gamma in C++

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CConfigManager.md

Loads sunset profiles and the maximum gamma value from the configuration manager. These are read-only after initialization.

```cpp
profiles = g_pConfigManager->getSunsetProfiles();
MAX_GAMMA = g_pConfigManager->getMaxGamma();
```

--------------------------------

### Scan Directory for Socket Path

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Discover the socket path by scanning the Hypr user directories for the .hyprsunset.sock file.

```bash
SOCKET=$(ls /run/user/$(id -u)/hypr/*/.hyprsunset.sock | head -1)
```

--------------------------------

### Get Maximum Gamma Multiplier

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CConfigManager.md

Retrieves the maximum gamma multiplier from the configuration. This value is expected to be a percentage and is converted to a decimal before being returned. The function internally handles potential casting errors by logging and aborting.

```cpp
float CConfigManager::getMaxGamma();
```

```cpp
float maxGamma = g_pConfigManager->getMaxGamma();  // e.g., 1.5
std::cout << "Max gamma: " << (maxGamma * 100) << "%\n";  // "Max gamma: 150%"
```

--------------------------------

### Get Current Profile

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CHyprsunset.md

Determines the index of the profile currently applicable based on local time. Returns -1 if no profiles are defined, or the index of the first profile whose time is greater than or equal to the current time.

```cpp
int CHyprsunset::currentProfile();
```

--------------------------------

### Reset Error Cases

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/api-reference/CIPCSocket.md

Illustrates error conditions for the reset command, including when no profile is loaded or an invalid field is specified.

```bash
reset temperature  (when no profile loaded)
→ "No profile is currently loaded"
```

```bash
reset foobar
→ "Invalid reset value (should be either temperature, gamma or identity)"
```

--------------------------------

### temperature — Query/Set Color Temperature

Source: https://github.com/hyprwm/hyprsunset/blob/main/_autodocs/ipc-protocol.md

Allows users to get or modify the color temperature (blue-light filter intensity) of Hyprsunset. Supports querying the current temperature, setting an absolute value, or adjusting it incrementally.

```APIDOC
## temperature — Query/Set Color Temperature

### Description
Get or modify the color temperature (blue-light filter intensity).

### Method
This is an IPC command, typically sent over a Unix domain socket.

### Endpoint
`/run/user/1000/hypr/0/.hyprsunset.sock` (Unix domain socket)

### Parameters
#### Command Forms
- `temperature`: Query current temperature as Kelvin.
- `temperature <value>`: Set absolute temperature to N Kelvin (1000–20000).
- `temperature +<value>`: Increase temperature by N Kelvin (Unclamped).
- `temperature -<value>`: Decrease temperature by N Kelvin (Unclamped).

#### Argument Type
- For setting temperature: Integer

### Return Value
- Query: `"<kelvin>"` (e.g., `"3500"`)
- Set: `"ok"` on success
- Error: Error message string (e.g., `"Invalid temperature (should be an integer in range 1000-20000)"`)

### Examples
```bash
# Get current temperature
echo "temperature" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "3500"

# Set to warm (sunset-like)
echo "temperature 3000" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "ok"

# Increase by 500K (cooler)
echo "temperature +500" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "ok"

# Decrease by 1000K (warmer)
echo "temperature -1000" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "ok"

# Try to exceed range
echo "temperature 500" | nc -U /run/user/1000/hypr/0/.hyprsunset.sock
# Output: "Invalid temperature (should be an integer in range 1000-20000)"
```
```