Skip to main content

Crate option_sdk

Crate option_sdk 

Source
Expand description

Shared paths, identity, config, crash, doctor, and terminal helpers for Option family apps (optionSDK).

§optionSDK

Shared paths, identity, and helpers for Option family apps (opsh, optionTerm, optionMusic, optionFiles, optionCalendar, optionSearch, …).

Local-first. No network. No daemon.

§Install

optionSDK = "0.1"

Path dependency while developing next to the other repos:

optionSDK = { path = "../optionSDK" }

In Rust, the crate is imported as option_sdk:

use option_sdk::App;

§Usage

use option_sdk::{App, color_on_stderr, color_on_stdout, expand_tilde};

let app = App::OPSH;
let _cfg = app.config_toml(); // ~/.option/opsh/config.toml
let _history = app.path("history"); // ~/.option/opsh/history
// app.ensure()? and app.ensure_cache()? create dirs + migrate legacy trees

assert_eq!(app.mark(), "❯");
assert_eq!(app.bundle_id(), "io.option.opsh");
assert_eq!(expand_tilde("~/Music"), option_sdk::home_dir().join("Music"));
let _ = color_on_stdout(); // NO_COLOR + stdout is a TTY
let _ = color_on_stderr(); // NO_COLOR + stderr is a TTY

Typed TOML config under ~/.option/<app>/config.toml:

use option_sdk::App;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Default)]
struct Settings {
    week_start: Option<String>,
}

// Creates the file with defaults on first run; reads it afterwards.
let settings = App::CAL.load_config::<Settings>()?;
App::CAL.save_config(&settings)?;

§Features (v0.1.6)

AreaAPI
Pathsoption_root(), home_dir(), expand_tilde(), App::dir(), config_toml(), cache_dir(), keys_toml(), session_toml(), path()
EnsureApp::ensure(), App::ensure_cache() — create dirs + migrate known legacy trees
OverrideOPTION_HOME — replace ~/.option (tests / sandboxes)
Migratemigrate_dir(), migrate_file() for app-specific leftovers
Identityid, mark (◆ ❯ ♪ ◷ ◇ ⌕), display name, io.option.* bundle id
Colorcolor_enabled() (NO_COLOR), color_on_stdout() / color_on_stderr() (NO_COLOR + TERM≠dumb + TTY)
Persistenceatomic_write() — flush and sync a sibling temporary file before replacement
Configload_toml(), load_toml_chain(), save_toml(), App::load_config(), App::save_config() — typed TOML via atomic_write()
Crashinstall_crash_hook(), crash_log_path() — append panic entries to ~/.option/<app>/crash.log
Doctordoctor::Report / doctor::Check / doctor::checks::* — text and JSON health reports
TermStyle — ANSI bold/dim/ok/warn/err + mark_line(); Style::stdout() / stderr() honor terminal detection
User dirsuser_dirs::data_home() / config_home() / cache_home() / documents() / music() / downloads() / pictures() — XDG-aware, user-dirs.dirs included

§Versioning

See CHANGELOG.md.

§Layout

~/.option/          # or $OPTION_HOME
  opsh/
  terminal/
  music/
  files/
  os/
  de/
  cal/
  search/           # optionSearch (legacy `needle/` migrated once)

§Environment

OPTION_HOME   non-empty value replaces ~/.option (absolute path recommended;
              empty value falls through to ~/.option; relative paths allowed
              but discouraged — they resolve against the process CWD)
HOME          primary home lookup; USERPROFILE is the Windows fallback;
              when neither is set, home resolves to "." (CWD-relative)
NO_COLOR      when set to any value (even empty), color output is disabled
              (see https://no-color.org/)
TERM=dumb     also disables color in color_on_stdout() / color_on_stderr()
XDG_*         XDG_DATA_HOME / XDG_CONFIG_HOME / XDG_CACHE_HOME and
              XDG_DOCUMENTS_DIR / XDG_MUSIC_DIR / XDG_DOWNLOAD_DIR /
              XDG_PICTURES_DIR: absolute values honored by user_dirs::*;
              empty or relative values are ignored; on Unix,
              $XDG_CONFIG_HOME/user-dirs.dirs supplies localized names
~             expand_tilde() expands only "~" and "~/..." via home_dir();
              "~user/..." is passed through unchanged

§License

Apache-2.0 — see the LICENSE file in the repository.

Modules§

doctor
Shared doctor report (text and JSON) for Option family apps.
user_dirs
XDG base directories and localized user folders, without the dirs crate.

Structs§

App
An Option family application.
Style
Whether ANSI color is enabled, plus the escape helpers.

Enums§

ConfigError
Errors from TOML config load/save.

Functions§

atomic_write
Write bytes through a sibling temporary file and replace the destination.
color_enabled
Whether ANSI / terminal color should be used.
color_on_stderr
Whether stderr should use color: color_enabled, TERM is not dumb, and stderr is a terminal.
color_on_stdout
Whether stdout should use color: color_enabled, TERM is not dumb, and stdout is a terminal.
crash_log_path
~/.option/<dir>/crash.log.
expand_tilde
Expand a leading ~ or ~/… using home_dir.
home_dir
Resolve the user home directory.
install_crash_hook
Install the crash hook once per process.
load_toml
Load a TOML file as T.
load_toml_chain
Load the first existing file from paths, returning the winning path too.
migrate_dir
Move legacy → new once when new is missing and legacy exists.
migrate_file
Move a single file legacy → new once when new is missing and legacy exists.
option_root
~/.option — shared root for all Option family apps.
save_toml
Serialize value as pretty TOML and persist it via crate::atomic_write.