{"id":16397515,"url":"https://github.com/marcoradocchia/microxdg","last_synced_at":"2025-03-23T04:32:11.122Z","repository":{"id":177088532,"uuid":"655444131","full_name":"marcoradocchia/microxdg","owner":"marcoradocchia","description":"An XDG Base Directory Specification Rust library that aims to be conservative on memory allocation and overall memory footprint.","archived":false,"fork":false,"pushed_at":"2024-11-09T12:22:57.000Z","size":163,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-18T18:00:04.201Z","etag":null,"topics":["appdir","basedir","cache","config","data","directories","directory","executable","file","home","path","runtime","rust","rust-lang","state","xdg","xdg-basedir","xdg-compliance","xdg-user-dirs"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcoradocchia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"marcoradocchia"}},"created_at":"2023-06-18T22:51:19.000Z","updated_at":"2025-01-21T08:18:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"243a7fd4-cec2-4fe1-9bb1-25f57d51d15a","html_url":"https://github.com/marcoradocchia/microxdg","commit_stats":null,"previous_names":["marcoradocchia/microxdg"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoradocchia%2Fmicroxdg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoradocchia%2Fmicroxdg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoradocchia%2Fmicroxdg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoradocchia%2Fmicroxdg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcoradocchia","download_url":"https://codeload.github.com/marcoradocchia/microxdg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245056892,"owners_count":20553854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appdir","basedir","cache","config","data","directories","directory","executable","file","home","path","runtime","rust","rust-lang","state","xdg","xdg-basedir","xdg-compliance","xdg-user-dirs"],"created_at":"2024-10-11T05:10:18.306Z","updated_at":"2025-03-23T04:32:11.106Z","avatar_url":"https://github.com/marcoradocchia.png","language":"Rust","funding_links":["https://github.com/sponsors/marcoradocchia"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e\u003ccode\u003emicroxdg\u003c/code\u003e\u003c/h1\u003e\n\n  ![GitHub source size](https://img.shields.io/github/languages/code-size/marcoradocchia/microxdg?color=ea6962\u0026logo=github)\n  ![GitHub open issues](https://img.shields.io/github/issues-raw/marcoradocchia/microxdg?color=%23d8a657\u0026logo=github)\n  ![GitHub open pull requests](https://img.shields.io/github/issues-pr-raw/marcoradocchia/microxdg?color=%2389b482\u0026logo=github)\n  ![GitHub sponsors](https://img.shields.io/github/sponsors/marcoradocchia?color=%23d3869b\u0026logo=github)\n  ![GitHub license](https://img.shields.io/github/license/marcoradocchia/microxdg?color=%23e78a4e)\n  ![Crates.io downloads](https://img.shields.io/crates/d/microxdg?label=crates.io%20downloads\u0026logo=rust)\n  ![Crates.io version](https://img.shields.io/crates/v/microxdg?logo=rust\u0026color=%23d8a657)\n\u003c/div\u003e\n\nAn **XDG Base Directory Specification** Rust library that aims to be\nconservative on memory allocation and overall memory footprint.\n\n# Usage\n\n## Dependency\n\nAdd `microxdg` as a dependency to your Rust project by running the following\n`cargo` command in your project directory:\n```sh\ncargo add microxdg\n```\n\nAlternatively, add the following line in the `[dependencies]` section of your\n`Cargo.toml`:\n```toml\nmicroxdg = \"0.2.0\"\n```\n\n## API\n\nThe `microxdg` API consists in two main `structs`:\n- `Xdg`, an implementation of the _XDG Base Directory Specification_;\n- `XdgApp`, an implementation of the _XDG Base Directory Specification_ with\n  extent to application-specific (or project-specific) subdirectories.\n\n\u003e **Note**: the latter's associated functions and methods are a superset of\n\u003e those implemented for `Xdg`. For this reason, it should be preferred only in\n\u003e case you need access to application-specific subdirectories.\n\nFor the complete documentation, consult \u003chttps://docs.rs/microxdg/latest\u003e.\n\n### Retrieve user-specific XDG directories\n\nThe following example illustrates how to retrieve the _user-specific_ XDG\n**configuration** directory:\n```rust\nuse microxdg::{Xdg, XdgError};\n\nfn main() -\u003e Result\u003c(), XdgError\u003e {\n    let xdg = Xdg::new()?;\n    let config_dir = xdg.config()?;\n\n    /* Do something with `config_dir`... */\n\n    Ok(())\n}\n```\n\nThe `Xdg::config` method returns the _user-specific_ XDG configuration\ndirectory specified by the `XDG_CONFIG_HOME` environment variable.\nFalls back to `$HOME/.config` or `/home/$USER/.config` if such environment\nvariable is not set, or is set to an empty value.\n\nReturns an error (`XdgError`) in the following cases:\n- the `XDG_CONFIG_HOME` environment variable is set, but its value represents\n  a relative path;\n- the `XDG_CONFIG_HOME` environment variable is set, but its value represents\n  invalid unicode.\n\nAnalogous methods are available for each of the other XDG directories listed\nin the specification:\n- `Xdg::cache`;\n- `Xdg::data`;\n- `Xdg::state`;\n- `Xdg::bin`;\n- `Xdg::runtime`.\n\nBelow a table illustrating the environment variable and corresponding fallbacks\nfor each of the XDG directories:\n\n| XDG Base Directory | Environment variable | Fallback - `HOME` set  | Fallback - `HOME` not set  |\n| ------------------ | -------------------- | ---------------------- | -------------------------- |\n| _Cache_            | `XDG_CACHE_HOME`     | `$HOME/.cache`         | `/home/$USER/.cache`       |\n| _Configuration_    | `XDG_CONFIG_HOME`    | `$HOME/.config`        | `/home/$USER/.config`      |\n| _Data_             | `XDG_DATA_HOME`      | `$HOME/.local/share`   | `/home/$USER/.local/share` |\n| _State_            | `XDG_STATE_HOME`     | `$HOME/.local/state`   | `/home/$USER/.local/state` |\n| _Bin_              | `XDG_BIN_HOME`       | `$HOME/.local/bin`     | `/home/$USER/.local/bin`   |\n| _Runtime_          | `XDG_RUNTIME_DIR`    | -                      | -                          |\n\n### Retrieve user-specific XDG application subdirectories\n\nThe following example illustrates how to retrieve the _user-specific_ XDG\n**data** application subdirectory:\n```rust\nuse microxdg::{XdgApp, XdgError};\n\nfn main() -\u003e Result\u003c(), XdgError\u003e {\n    let xdg = XdgApp::new(\"app_name\")?;\n    let app_data_dir = xdg.app_data()?;\n\n    /* Do something with `app_data_dir`... */\n\n    Ok(())\n}\n```\n\nThe `Xdg::app_data` method returns the _user-specific_ XDG data subdirectory\nfor the given application. It uses the XDG directory specified by the\n`XDG_DATA_HOME` environment variable, if available. Falls back to\n`$HOME/.local/share/app_name` or `/home/$USER/.local/share/app_name` if such\nenvironment variable is not set, or is set to an empty value.\n\nAlso, it returns an error (`XdgError`) in the following cases:\n- the `XDG_DATA_HOME` environment variable is set, but its value represents\n  a relative path;\n- the `XDG_DATA_HOME` environment variable is set, but its value represents\n  invalid unicode.\n\nAnalogous methods are available for other XDG application subdirectories:\n- `Xdg::app_cache`;\n- `Xdg::app_config`;\n- `Xdg::app_state`.\n\nBelow a table illustrating the environment variable and corresponding fallbacks\nfor each of the XDG directories:\n\n| XDG Application Subdirectory | Environment variable | Fallback - `HOME` set         | Fallback - `HOME` not set           |\n| ---------------------------- | -------------------- | ----------------------------- | ----------------------------------- |\n| _App Cache_                  | `XDG_CACHE_HOME`     | `$HOME/.cache/app_name`       | `/home/$USER/.cache/app_name`       |\n| _App Configuration_          | `XDG_CONFIG_HOME`    | `$HOME/.config/app_name`      | `/home/$USER/.config/app_name`      |\n| _App Data_                   | `XDG_DATA_HOME`      | `$HOME/.local/share/app_name` | `/home/$USER/.local/share/app_name` |\n| _App State_                  | `XDG_STATE_HOME`     | `$HOME/.local/state/app_name` | `/home/$USER/.local/state/app_name` |\n\n### Retrieve user-specific XDG files\n\nThe following example illustrates how to retrieve the path to a file contained\nin the _user-specific_ XDG **cache** directory:\n```rust\nuse microxdg::{XdgApp, XdgError};\n\nfn main() -\u003e Result\u003c(), XdgError\u003e {\n    let xdg = Xdg::new()?;\n    let cache_file = xdg.cache_file(\"file_name\")?;\n\n    /* Do something with `cache_file`... */\n\n    Ok(())\n}\n```\n\nThe `Xdg::cache_file` method returns the path to a _user-specific_ XDG cache\nfile. It uses the XDG directory specified by the `XDG_CACHE_HOME`\nenvironment variable, if available. Falls back to `$HOME/.cache/file_name` or\n`/home/$USER/.cache/file_name` if such environment variable is not set, or is\nset to an empty value.\n\nAlso, it returns an error (`XdgError`) in the following cases:\n- the `XDG_CACHE_HOME` environment variable is set, but its value represents\n  a relative path;\n- the `XDG_CACHE_HOME` environment variable is set, but its value represents\n  invalid unicode.\n\nAnalogous methods are available other XDG directories:\n- `Xdg::config_file`;\n- `Xdg::data_file`;\n- `Xdg::state_file`;\n- `Xdg::bin_file`.\n\n\u003e **Note**: these methods do not guarantee either the path exists or points to\n\u003e a regular file.\n\n### Retrieve user-specific XDG application files\n\nThe following example illustrates how to retrieve the path to a file contained\nin the _user-specific_ XDG **state** application subdirectory:\n```rust\nuse microxdg::{XdgApp, XdgError};\n\nfn main() -\u003e Result\u003c(), XdgError\u003e {\n    let xdg = XdgApp::new(\"app_name\")?;\n    let app_state_file = xdg.app_state_file(\"file_name\")?;\n\n    /* Do something with `app_state_file`... */\n\n    Ok(())\n}\n\n```\n\nThe `Xdg::app_state_file` returns the path to a _user-specific_ XDG application\nfile. It uses the XDG application subdirectory specified by\n`$XDG_STATE_HOME/app_name`, if the `XDG_STATE_HOME` environment variable is\navailable. Falls back to `$HOME/.local/state/app_name/file_name` or\n`/home/$USER/.local/state/file_name` if such environment variable is not set,\nor is set to an empty value.\n\nAlso, it returns an error (`XdgError`) in the following cases:\n- the `XDG_STATE_HOME` environment variable is set, but its value represents\n  a relative path;\n- the `XDG_STATE_HOME` environment variable is set, but its value represents\n  invalid unicode.\n\nAnalogous methods are available for other XDG directories:\n- `Xdg::app_cache_file`;\n- `Xdg::app_config_file`;\n- `Xdg::app_data_file`.\n\n\u003e **Note**: these methods do not guarantee either the path exists or points to\n\u003e a regular file.\n\n### Retrieve system-wide, preference-ordered, XDG directories\n\nThe following example illustrates how to retireve the _system-wide_,\npreference-ordered, XDG **data** directories:\n```rust\nuse microxdg::{Xdg, XdgError};\n\nfn main() -\u003e Result\u003c(), XdgError\u003e {\n    let xdg = Xdg::new()?;\n    let sys_data_dirs = Xdg::sys_data()?;\n  \n    /* Do something with `sys_data_dirs`... */\n  \n    Ok(())\n}\n```\n\nThe `Xdg::sys_data` associated function returns the _system-wide_,\npreference-ordered, XDG data directories specified by the `XDG_DATA_DIRS`\nenvironment variable. Falls back to `/usr/local/share:/usr/share` if such\nenvironment variable is not set, or is set to an empty value.\n\nAlso, it returns an error (`XdgError`) in the following cases:\n- the `XDG_DATA_DIRS` environment variable is set, but one (or more) path(s)\n  in the colon separated value represents a relative path;\n- the `XDG_DATA_DIRS` environment variable is set, but its value represents\n  invalid unicode.\n\nAn analogous method is available for the system-wide XDG configuration\ndirectories: `Xdg::sys_config`.\n\nBelow a table illustrating the environment variable and corresponding fallbacks\nfor each of the system-wide, preference-ordered, XDG directories:\n\n| XDG Base Directory  | Environment variable | Fallback                      |\n| ------------------- | -------------------- | ----------------------------- |\n| _Configuration_     | `XDG_CONFIG_DIRS`    | `/etc/xdg`                    |\n| _Data_              | `XDG_DATA_DIRS`      | `/usr/local/share:/usr/share` |\n\n\u003e **Note**: the `XDG_CONFIG_DIRS` and `XDG_DATA_DIRS` environment variables\n\u003e should be set to a colon separated value, where each entry represents a\n\u003e path to a system XDG directory. The order denotes the importace: the first\n\u003e directory the most important, the last directory the least important.\n\n### Retrieve system-wide, preference-ordered, XDG application subdirectories\n\nThe following example illustrates how to retrieve the _system-wide_,\npreference-ordered, XDG **config** application subdirectories:\n```rust\nuse microxdg::{XdgApp, XdgError};\n\nfn main() -\u003e Result\u003c(), XdgError\u003e {\n    let xdg = XdgApp::new(\"app_name\")?;\n    let app_sys_config_dirs = xdg.app_sys_config()?;\n\n    /* Do something with `app_sys_config_dirs`... */\n\n    Ok(())\n}\n```\n\nThe `XdgApp::app_sys_config` method returns the _system-wide_,\npreference-ordered, XDG application configuration subdirectories for the given\napplication. It uses the directories specified by the `XDG_CONFIG_DIRS`\nenvironment variable, if available. Falls back to `/etc/xdg/app_name` if such\nenvironment variable is not set, or is set to an empty value.\n\nAlso, it returns an error (`XdgError`) in the following cases:\n- the `XDG_CONFIG_DIRS` environment variable is set, but one (or more) path(s)\n  in the colon separated value represents a relative path;\n- the `XDG_CONFIG_DIRS` environment variable is set, but its value represents\n  invalid unicode.\n\nAn analogous method is available for the system-wide XDG application data\nsubdirectories: `XdgApp::app_sys_data`.\n\nBelow a table illustrating the environment variable and corresponding fallbacks\nfor each of the system-wide, preference-ordered, XDG app subdirectories:\n\n| XDG Base Directory | Environment variable | Fallback                                        |\n| ------------------ | -------------------- | ----------------------------------------------- |\n| _Configuration_    | `XDG_CONFIG_DIRS`    | `/etc/xdg/app_name`                             |\n| _Data_             | `XDG_DATA_DIRS`      | `/usr/local/share/app_name:/usr/share/app_name` |\n\n\u003e **Note**: the `XDG_CONFIG_DIRS` and `XDG_DATA_DIRS` environment variables\n\u003e should be set to a colon separated value, where each entry represents a\n\u003e path to a system XDG directory. The order denotes the importace: the first\n\u003e directory the most important, the last directory the least important.\n\n## Search user-specific XDG files\n\nThe following example illustrates how to search a file inside XDG **config**\ndirectories:\n```rust\nuse microxdg::{Xdg, XdgError};\n\nfn main() -\u003e Result\u003c(), XdgError\u003e {\n    let xdg = Xdg::new()?;\n    match xdg.search_config_file(\"file_name\")? {\n        Some(config_file) =\u003e {\n            /* Do something with `config_file`... */\n        }\n        None =\u003e {\n            /* Do something else... */\n        }\n    }\n\n    Ok(())\n}\n```\n\nThe `Xdg::search_config_file` method returns an `Option\u003cPathBuf\u003e`. Its variants\nare:\n- `Some(file)`, in the case the file was found inside one of the XDG\n  configuration directories. The lookup order is:\n  - _user-specific_ XDG configuration directory specified by the\n    `XDG_CONFIG_HOME` environment variable if available, or the corresponding\n    fallbacks if such environment variable is not set or set to an empty value;\n  - _system-wide_ XDG configuration directories specified by the\n    `XDG_CONFIG_DIRS` environment variable if available, or the corresponding\n    fallback if such environment variable is not set or set to an empty value;\n- `None`, in the case the file was **not** found inside any of the XDG\n  configuration directories (either _user-specific_ or _system-wide_).\n\nAlso, it returns an error (`XdgError`) in the following cases:\n- the `XDG_CONFIG_HOME` environment variable is set, but its value represents\n  a relative path;\n- the `XDG_CONFIG_HOME` environment variable is set, but its value represents\n  invalid unicode;\n- the file was **not** found inside the _user-specific_ XDG data directory and:\n  - the `XDG_CONFIG_DIRS` environment variable is set, but one (or more) path(s)\n    in the colon separated value represents a relative path;\n  - the `XDG_CONFIG_DIRS` environment variable is set, but its value represents\n    invalid unicode.\n\nAnalogous methods are available to search files inside the other XDG\ndirectories:\n- `Xdg::search_cache_file`;\n- `Xdg::search_data_file`;\n- `Xdg::search_state_file`;\n- `Xdg::search_bin_file`.\n\n## Search user-specific XDG application files\n\nThe following example illustrates how to search a file inside XDG **data**\napplication subdirectories:\n```rust\nuse microxdg::{XdgApp, XdgError};\n\nfn main() -\u003e Result\u003c(), XdgError\u003e {\n    let xdg = XdgApp::new(\"app_name\");\n    match xdg.search_app_data_file(\"file_name\")? {\n        Some(app_data_file) =\u003e {\n            /* Do something with `app_data_file` ... */\n        }\n        None =\u003e {\n            /* Do something else... */\n        }\n    }\n\n    Ok(())\n}\n```\n\nThe `Xdg::search_app_data_file` method returns an `Option\u003cPathBuf\u003e`. Its\nvariants are:\n- `Some(app_data_file)`, in the case the file was found inside one of the XDG\n  data subdirectories. The lookup order is:\n  - _user-specific_ XDG application data subdirectory specified by the\n    `XDG_DATA_HOME` environment variable if available, or falls back to\n    `$HOME/.local/share/app_name` if such environment variable is not set or\n    set to an empty value;\n  - _system-wide_ XDG configuration directories specified by the\n    `XDG_CONFIG_DIRS` environment variable if available, or falls back to\n    `/usr/local/share/app_name:/usr/share/app_name` if such variable\n    environment is not set or set to an empty value;\n- `None`, in the case the file was **not** found inside any of the XDG\n  configuration directories (either _user-specific_ or _system-wide_).\n\nAlso, it returns an error (`XdgError`) in the following cases:\n- the `XDG_DATA_HOME` environment variable is set, but its value represents\n  a relative path;\n- the `XDG_DATA_HOME` environment variable is set, but its value represents\n  invalid unicode;\n- the file was **not** found inside the _user-specific_ XDG data directory and:\n  - the `XDG_DATA_DIRS` environment variable is set, but one (or more) path(s)\n    in the colon separated value represents a relative path;\n  - the `XDG_DATA_DIRS` environment variable is set, but its value represents\n    invalid unicode.\n\nAnalogous methods are available to search files inside the other XDG\napplication subdirectories:\n- `Xdg::search_app_cache_file`;\n- `Xdg::search_app_config_file`;\n- `Xdg::search_app_state_file`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcoradocchia%2Fmicroxdg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcoradocchia%2Fmicroxdg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcoradocchia%2Fmicroxdg/lists"}