flk 0.6.2

A CLI tool for managing flake.nix devShell environments
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# API Documentation

The flk library exposes Rust APIs for programmatic access to flake generation and parsing.

## Generating Documentation

Build the API documentation locally:

```bash
cargo doc --no-deps --open
```

Or with all features and dependencies:

```bash
cargo doc --all-features --open
```

## Module Overview

### `flk::flake`

Core flake functionality:

- **`flk::flake::generator`** - Template loading and flake generation
  - `generate_flake(project_type)` - Generate profile content for a project type
  - `generate_helper_module()` - Generate the `.flk/default.nix` loader
  - `generate_pins()` - Generate empty pins file

- **`flk::flake::parsers`** - Nix file parsing and modification
  - `packages` - Parse/modify `packages = [ ... ];` sections
  - `env` - Parse/modify `envVars = { ... };` sections  
  - `commands` - Parse/modify shell hook commands
  - `overlays` - Parse/modify `pins.nix` for version pinning
  - `flake` - Parse top-level flake structure
  - `utils` - Profile resolution and parsing helpers

- **`flk::flake::interfaces`** - Data structures
  - `FlakeConfig` - Complete flake configuration
  - `Profile` - Single profile with packages, commands, env vars
  - `Package` - Package entry with optional version
  - `EnvVar` - Environment variable key-value pair

- **`flk::flake::nix_render`** - Safe Nix syntax rendering
  - `nix_string(s)` - Escape string for Nix double-quoted strings
  - `nix_attr_key(s)` - Format attribute key (quote if needed)

### `flk::utils`

Utility functions:

- **`flk::utils::backup`** - Lockfile backup management
- **`flk::utils::visual`** - Spinner and progress display

## Example Usage

```rust
use flk::flake::generator::generate_flake;
use flk::flake::parsers::packages::parse_packages_section;

// Generate a Rust profile template
let profile_content = generate_flake("rust")?;

// Parse packages from an existing profile
let content = std::fs::read_to_string(".flk/profiles/rust.nix")?;
let section = parse_packages_section(&content)?;

// Add a package (returns new content directly)
let new_content = section.add_package(&content, "ripgrep", None);
std::fs::write(".flk/profiles/rust.nix", new_content)?;
```

## Contributing to the API

When contributing:

- Document all public items with `///` doc comments
- Include `# Arguments`, `# Returns`, and `# Errors` sections where applicable
- Add examples in doc comments for non-obvious behavior
- Run `cargo doc --no-deps` before submitting to check for warnings
- Keep internal/unstable functions prefixed with underscore (`_parse_*`)