Crate app_data 

English Documentation

# app_data

A cross-platform Rust library for managing application data directories on Windows, macOS, and Linux.

Overview

The app_data crate provides a simple and standardized way to manage application data directories across different platforms. It automatically handles platform-specific directory conventions and ensures directories are created when needed.

Features

• ✅ Cross-platform support (Windows, macOS, Linux)
• ✅ Automatic directory creation
• ✅ Local and system directory modes
• ✅ Custom error types with detailed messages
• ✅ Zero dependencies (only uses standard library)

Directory Principles

The AppData directory follows these principles:

• Default behavior: Searches for data directory under the startup path
• Fallback: If the data directory doesn’t exist under the startup path, creates data directory in the system user directory
• Force local mode: When force_local is enabled, always creates directories in the startup path

Platform-Specific Directories

Windows

• Data: %APPDATA%\app_name

macOS

• Data: ~/Library/Application Support/app_name

Linux

• Data: $XDG_DATA_HOME/app_name or ~/.local/share/app_name

Usage

Basic Usage

use app_data::AppData;

// Create with default settings
let app_data = AppData::default();

// Or specify application name
let app_data = AppData::new("my_app");

// Get data directory (creates if not exists)
let data_dir = app_data.ensure_data_dir()?;
println!("Data directory: {}", data_dir.display());

// Get file path in data directory
let config_file = app_data.get_file_path("config.json")?;

Force Local Mode

use app_data::AppData;

// Force creation in startup directory
let app_data = AppData::with_force_local("my_app", true);
let data_dir = app_data.ensure_data_dir()?;
// Creates: ./data/

Error Handling

use app_data::{AppData, AppDataError};

match app_data.ensure_data_dir() {
    Ok(dir) => println!("Directory: {}", dir.display()),
    Err(AppDataError::EnvVarNotFound(var)) => {
        eprintln!("Environment variable {} not found", var);
    }
    Err(AppDataError::IoError(msg)) => {
        eprintln!("IO error: {}", msg);
    }
    Err(AppDataError::CurrentDirError(msg)) => {
        eprintln!("Failed to get current directory: {}", msg);
    }
}

Examples

See the examples/ directory for more complete examples.

License

MIT

中文文档

# app_data

一个跨平台的 Rust 库，用于管理 Windows、macOS 和 Linux 上的应用数据目录。

概述

app_data 库提供了一种简单且标准化的方式来管理不同平台上的应用数据目录。它会自动处理平台特定的目录约定，并在需要时确保目录被创建。

特性

• ✅ 跨平台支持（Windows、macOS、Linux）
• ✅ 自动创建目录
• ✅ 本地和系统目录模式
• ✅ 自定义错误类型，提供详细错误信息
• ✅ 零依赖（仅使用标准库）

目录原则

AppData 目录遵循以下原则：

• 默认行为：在启动路径下搜索 data 目录
• 回退机制：如果启动路径下不存在 data 目录，则在系统用户目录下创建 data 目录
• 强制本地模式：启用 force_local 时，始终在启动路径下创建目录

平台特定目录

Windows

• 数据目录：%APPDATA%\app_name

macOS

• 数据目录：~/Library/Application Support/app_name

Linux

• 数据目录：$XDG_DATA_HOME/app_name 或 ~/.local/share/app_name

使用方法

基本使用

use app_data::AppData;

// 使用默认设置创建
let app_data = AppData::default();

// 或指定应用名称
let app_data = AppData::new("my_app");

// 获取数据目录（如果不存在则创建）
let data_dir = app_data.ensure_data_dir()?;
println!("数据目录: {}", data_dir.display());

// 获取数据目录中的文件路径
let config_file = app_data.get_file_path("config.json")?;

强制本地模式

use app_data::AppData;

// 强制在启动目录下创建
let app_data = AppData::with_force_local("my_app", true);
let data_dir = app_data.ensure_data_dir()?;
// 创建：./data/

错误处理

use app_data::{AppData, AppDataError};

match app_data.ensure_data_dir() {
    Ok(dir) => println!("目录: {}", dir.display()),
    Err(AppDataError::EnvVarNotFound(var)) => {
        eprintln!("环境变量 {} 未找到", var);
    }
    Err(AppDataError::IoError(msg)) => {
        eprintln!("IO 错误: {}", msg);
    }
    Err(AppDataError::CurrentDirError(msg)) => {
        eprintln!("获取当前目录失败: {}", msg);
    }
}

示例

查看 examples/ 目录获取更多完整示例。

许可证

MIT

Structs

AppData

Examples

Enums

AppDataError

Custom error type