tktax-config 0.2.2

Configuration handling for tktax, integrating environment- and file-based settings.
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
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# tktax-config

A Rust crate providing configuration logic for the _tktax_ ecosystem. This crate merges file-based and environment-based settings into a centralized data structure, facilitating robust and extensible configuration management. The crate resolves potential conflicts with a predictable order, ensuring determinism in production environments (ἐν διατάξει).

## Overview

`tktax-config` supplies:

- **GeneralConfig**: Holds global flags, e.g., `long` for controlling operational modes.
- **AccountsConfig**: Structures bank accounts, savings accounts, and credit accounts via nested `HashMap`s.
- **ProgramConfig**: Aggregates sub-configurations and includes specialized logic for Amazon item mapping. Draws from local TOML files (e.g., `config.toml`) and environment variables prefixed with `TKTAX`.

## Usage

1. **Add as a Dependency**

   In your project’s `Cargo.toml`:
   ```toml
   [dependencies]
   tktax-config = { path = "../tktax-config" }
   ```
   (Adjust `path` or version as needed for your setup.)

2. **Instantiate the Config**

   ```rust
   fn main() {
       // Leverage the `Default` trait to parse from `config.toml` 
       // and environment variables (`TKTAX_*`).
       let config = tktax_config::ProgramConfig::default();

       // Example usage
       if config.general().long() {
           println!("Long-mode enabled!");
       }

       if let Some(accounts) = config.accounts() {
           // Access checking, savings, credit, etc.
       }
   }
   ```

3. **Environment Variables and File Overrides**

   - By default, `config.toml` is read from the current directory.
   - Environment variables such as `TKTAX_GENERAL_LONG=false` override file-based values.
   - Command-line options can be parsed (not shown here) to override defaults for ephemeral debugging.

## Detailed Structures

### `ProgramConfig`
- **`general: GeneralConfig`**  
  - Determines overarching behavior.
- **`accounts: Option<AccountsConfig>`**  
  - Houses checking, savings, and credit accounts.
- **`amazon: Option<AmazonConfig>`**  
  - Contains Amazon-related data for item mapping.

### `GeneralConfig`
- **`long: bool`**  
  - Defaults to `true`. Indicates whether certain processes run in extended form.

### `AccountsConfig`
- **`checking: Option<HashMap<u32, String>>`**  
  - Mapping of checking-account identifiers to descriptions.
- **`savings: Option<HashMap<u32, String>>`**  
  - Mapping of savings-account identifiers to descriptions.
- **`credit: Option<HashMap<u32, String>>`**  
  - Mapping of credit-account identifiers to descriptions.

### `AmazonConfig` (From tktax_amazon)
- Provided by the external `tktax-amazon` crate and integrated here.

## Example `config.toml`

```toml
[general]
long = true

[accounts.checking]
101 = "Main Checking"
202 = "Secondary Checking"

[accounts.savings]
303 = "Emergency Fund"
404 = "Holiday Savings"

[accounts.credit]
505 = "Primary Credit Card"
606 = "Travel Rewards Card"

# Example Amazon config would reside under [amazon] depending on tktax_amazon definitions
```

## Amazon-Specific Usage

- `create_amazon_item_map` method in `ProgramConfig` will yield an `AmazonItemMap`, derived from data in `[amazon]`. If no Amazon data is present, it returns `None`.

## Contributing

1. **Fork** the repository.
2. **Create** a feature branch.
3. **Commit** your changes with clear messages.
4. **Open** a Pull Request.

## License

This project is licensed under the [MIT License](LICENSE).  

---

**Happy configuring!**