# API guide
## Constructors
### `ConfigManager::for_app(app_name)`
Recommended for production desktop apps.
```rust
let manager = ConfigManager::<Settings>::for_app("my-app")?;
```
The app name must be a safe single path component.
Since 2.5.0, this constructor also reports when the platform configuration
directory itself cannot be resolved (for example, no `HOME` or `%APPDATA%` in
the environment), returning `ConfigError::Platform`. This is the constructor
to prefer specifically because it does not hide that failure.
### `ConfigManager::new()`
Convenience constructor that derives the app directory from the current
executable name.
```rust
let manager = ConfigManager::<Settings>::new();
```
This is convenient for examples and small tools, but `for_app()` is more stable
for production applications, and it is the only constructor that reports
platform-resolution failure. `new()` cannot report it without an API break —
if the platform configuration directory cannot be resolved, `new()` falls
back to the current directory rather than failing. Applications that run
where this is a real possibility (services or containers without a user
environment) should prefer `for_app()`, or supply a path explicitly with
`with_root_dir()`.
### `with_root_dir(path)`
Overrides the settings root directory.
```rust
let manager = ConfigManager::<Settings>::new().with_root_dir("./config");
```
Use this for tests, portable mode, app-managed storage locations, and sandboxed
hosts.
## File names
```rust
let manager = ConfigManager::<Settings>::for_app("my-app")?
.try_with_filename("preferences.json")?;
```
`try_with_filename()` validates that the value is a plain file name.
## Loading and saving
```rust
manager.save(&settings)?;
let settings = manager.load()?;
```
`save()` uses atomic replacement by default since 2.3.0. `load()` expects the
file to already exist.
For normal app startup:
```rust
let settings = manager.load_or_default()?;
```
## Save mode
```rust
use app_json_settings::SaveMode;
let manager = ConfigManager::<Settings>::for_app("my-app")?
.with_save_mode(SaveMode::Direct);
```
`SaveMode::Atomic` is the default. `SaveMode::Direct` is available when an
application intentionally wants direct overwrite behavior.
## Updates
```rust
})?;
```
`update()` performs a load-or-default, applies the closure, and saves the result
using the configured save mode.