# mjallen-lib Utility Functions

This directory contains utility functions that can be used to enhance your Nix configuration. These functions are inspired by the khanelinix repository and provide a more explicit and modular approach to building Nix configurations.

## Directory Structure

- `default.nix`: Main entry point that imports and exposes all utility functions
- `module/`: Utilities for module creation and option handling
- `file/`: Utilities for file handling and module discovery
- `system/`: Utilities for system configuration building

## How to Use

### 1. Import the Library

The library is already imported in your flake.nix file through the outputs-builder:

```nix
outputs-builder = channels: {
  formatter = inputs.treefmt-nix.lib.mkWrapper channels.nixpkgs ./treefmt.nix;
  
  # Add mjallen-lib to the flake outputs
  overlays = {
    mjallen-lib = final: prev: {
      mjallen-lib = (import ./lib { inherit inputs; }).mjallen-lib;
    };
  };
};
```

This makes the mjallen-lib available to all your modules through the extended lib.

### 2. Use the Module Utilities

The module utilities provide functions for creating modules with consistent options:

```nix
{ lib, ... }:
let
  inherit (lib.mjallen.module) mkModule mkOpt mkBoolOpt;
in
mkModule {
  name = "mymodule";
  description = "My awesome module";
  options = {
    setting1 = mkOpt lib.types.str "default" "Description of setting1";
    setting2 = mkBoolOpt false "Description of setting2";
  };
  config = {
    # Module implementation
  };
}
```

### 3. Use the File Utilities

The file utilities provide functions for file handling and module discovery:

```nix
{ lib, ... }:
let
  inherit (lib.mjallen.file) safeImport importModulesRecursive;
in
{
  # Import a file with error handling
  myConfig = safeImport ./my-config.nix {};
  
  # Import all modules recursively
  imports = importModulesRecursive ./modules;
}
```

### 4. Use the System Utilities

The system utilities provide functions for building system configurations:

```nix
{ lib, ... }:
let
  inherit (lib.mjallen.system.common) mkHomeManagerConfig;
in
{
  # Build home-manager configurations
  homeManagerConfig = mkHomeManagerConfig {
    extendedLib = lib;
    inputs = inputs;
    system = "x86_64-linux";
    matchingHomes = { ... };
  };
}
```

## Available Functions

### Module Utilities

- `mkModule`: Create a module with common options
- `mkOpt`: Create an option with a type, default value, and description
- `mkOpt'`: Create an option with a type and default value (no description)
- `mkBoolOpt`: Create a boolean option with a default value and description
- `mkBoolOpt'`: Create a boolean option with a default value (no description)
- `enabled`: Standard enable pattern
- `disabled`: Standard disable pattern
- `capitalize`: Capitalize a string
- `boolToNum`: Convert a boolean to a number
- `default-attrs`: Apply mkDefault to all attributes
- `force-attrs`: Apply mkForce to all attributes
- `nested-default-attrs`: Apply default-attrs to nested attributes
- `nested-force-attrs`: Apply force-attrs to nested attributes

### File Utilities

- `readFile`: Read a file and return its contents
- `pathExists`: Check if a file exists
- `safeImport`: Import a nix file with error handling
- `scanDir`: Scan a directory and return directory names
- `getFile`: Get a file path relative to the flake root
- `importModulesRecursive`: Recursively discover and import all Nix modules in a directory tree
- `scanSystems`: Recursively scan systems directory structure
- `filterNixOSSystems`: Filter systems for NixOS (Linux)
- `filterDarwinSystems`: Filter systems for Darwin (macOS)
- `scanHomes`: Scan homes directory structure for home configurations

### System Utilities

- `mkExtendedLib`: Extend the nixpkgs lib with mjallen-lib
- `mkNixpkgsConfig`: Create a nixpkgs configuration
- `mkHomeConfigs`: Create home configurations for a system and hostname
- `mkHomeManagerConfig`: Create a home-manager configuration
- `mkSpecialArgs`: Create special arguments for a system configuration