# 🚀 flaga: High-Performance Binary Flag System
**flaga** is a robust, thread-safe Rust library designed for managing complex feature flags, permissions, and system states using optimized bitwise arithmetic. It bridges the gap between low-level performance and high-level developer ergonomics.
### flaga is polish for flag, i was thinkin about a name, but many things were taken so i sought out the polish word and ran with it
---
## 🏗️ Core Philosophy
1. **Zero Boilerplate:** Use macros to generate entire flag structures in a single line.
2. **Thread Safety:** Built-in support for concurrent access using `Arc` and `RwLock`.
3. **Persistence:** Built-in support for binary (`bincode`) and human-readable (`JSON`) serialization.
4. **Flexibility:** Choose between **Static** (stack-allocated) and **Dynamic** (heap-allocated) flag descriptors.
---
## 📦 Quick Start
### 1. Define Your Flags
Using the `impl_flag_trait!` macro, you can create a new flag type with all bitwise operations ready to go.
```rust
use flagger::impl_flag_trait;
// Create a 64-bit flag container
impl_flag_trait!(SystemFlags, u64);
```
### 2. Create a Manager
The `FlagManager` is the brain of your system. Use the builder pattern to set it up.
```rust
let manager = FlagManager::new()
.with_file_path("flags.bin")
.add_extension_flag(".rs", "AUTO_SAVE", FlagType::Binary, 0b0001);
```
### 3. Set and Check Flags
The API is designed to be intuitive and fast.
```rust
manager.add_flag("DEBUG_MODE", FlagType::Binary, 0b0001, Some("Enables verbose logging"), None)?;
// Activate the flag
manager.set_flag("DEBUG_MODE")?;
// Check the state
if manager.check_flag("DEBUG_MODE")? {
println!("Debug mode is active!");
}
```
---
## 🛠️ Advanced Features
### Functional Triggers
Execute logic automatically based on flag states without writing `if/else` blocks everywhere.
```rust
let trigger = FlagTrigger::new(my_flags);
trigger.trigger_if(0b0001, || {
// This closure only runs if the 1st bit is set
initiate_shutdown();
});
```
### Complex Pattern Evaluation
Parse and evaluate complex boolean logic strings at runtime.
```rust
let is_allowed = parser.check_complex_pattern("!Network.Flag1 && Core.Flag0");
```
---
## 🗂️ Project Structure
| `flag` | Defines the core `Flag` trait for bitwise behavior. |
| `flag_manager` | The thread-safe coordinator for all flags. |
| `macros` | Code generation tools to eliminate boilerplate. |
| `flag_trigger` | Event-driven execution based on flag states. |
| `error` | Exhaustive error handling via `thiserror`. |
---
## 💾 Persistence Strategies
Flagger supports two modes of saving:
* **Total Recall:** Saves the entire manager state, including name mappings and extension logic.
* **Data-Only:** Saves only the raw bitmasks (perfect for minimal database storage).
---
## ⚖️ License
This project is licensed under the MIT License - see the `LICENSE` file for details.