Crate komichi

Crate komichi 

Source
Expand description

§小道 Komichi

komichi is a collection of tools to make working with file-system paths more convenient.

§Features

Some notable features of komichi:

  • Uses camino paths so that an application, using this crate, can treat paths like normal Rust string-like types.
  • EnvVal provides the ability to retrieve environment variable values and use a default value if the environment variable does NOT exist or have a value.
  • ExpandPath provides a relatively-fast ability to expand unicode-paths that:
    • may contain BASH-like variables; and
    • may start with a tilde; and
    • may not be absolute.
  • ExpandText provides a relatively-fast ability to expand given text or text from a file (using a callback function) that:
    • may contain BASH-like curly-bracket variables (aka identifiers)
  • ExpandTextWith provides a relatively-fast ability to expand given text or text from a file (using the Fetcher trait) that:
    • may contain BASH-like curly-bracket variables (aka identifiers)
  • LocalDirectories can provide application local ($HOME) path directory locations for:
    • cache files
    • config files
    • data files
    • log files
    • state files
  • SystemDirectories can provide application system path directories locations for:
    • system application cache files
    • system application config files
    • system application data files
    • system application log files
    • system application state files
    • system application install files

§Release Notes

§2.2.0 (2025-07-21)

  • Addition of Scrub
  • Adjusted to work with 2024 Addition

§2.1.0 (2025-06-24)

§2.0.0 (2025-02-21)

§1.0.3 (2024-04-01)

§1.0.1 (2024-03-25)

  • YANKED
  • Unix bug fixes

§1.0.0 (2024-03-25)

§Glossary

§Expansion

Expansion is the process of replacing an identifier (variable), in text, with a particular value.

§Identifier

An identifier is a unique name give to a specific variable in komichi. This crate uses BASH-like curly variables to denote an identifier.

  • Identifiers start with a dollar sign $; and,
  • are followed by an opening curly bracket {; and,
  • are followed by the identifier-name; and,
  • are followed by a closing curly bracket }.
§Identifier-name

Identifier-names have particular rules:

  • The first starting character, after the ${, must be one of _[a-z][A-Z]; and,
  • Any remaining characters must be of _[a-z][A-Z][0-9]
§Identifier Notes

  • The dollar-sign character, $, can be escaped by using two dollar-sign characters (e.g. $$).

  • When using ExpandPath, expand_path_with expand_path_strict_with, an identifier can omit the use of the curly brackets {..}, but it is not recommended. Desired outcomes cannot be guaranteed.

    For example the ‘path’ of $ONE_foo_bar is ambiguous and only the value for the entire identifier name ONE_foo_bar will be searched for. To remove the ambiguity use curly braces (e.g. ${ONE}_foo_bar).

Modules§

error
Komichi errors.

Structs§

EnvVal
Used to acquire an environment variable value with a fallback value.
ExpandPath
Expand any BASH-like-identifiers in a path using a callback function.
ExpandText
Provide the ability to expand BASH-like-curly-variables in text or in a file.
ExpandTextWith
Expand any BASH-like-identifiers in text or a file by obtaining values using the Fetcher trait.
LocalDirectories
Provide path locations for a given application name from a local perspective.
Scrub
Used to replace a user’s home directory, in the given path, with a tilde.
SystemDirectories
Provide path locations for a given application-name as if the given application-name was installed on the system (not installed in the user’s directory).

Traits§

Fetcher
A trait for types that can retrieve string-based data by a given key.

Functions§

expand_path_cwd
Prepend the current working directory (“CWD”) to the given path.
expand_path_strict_with
Strictly expand the given path with the given function/callback.
expand_path_tilde
Expand a starting tilde in the given path to the home directory.
expand_path_with
Expand the given path with the given function/callback.
expand_path_with_environ
Expand any environment variables in the given path
expand_text_strict_with
Return the given text, containing bash-like-curly variables that are expanded with values from the given callback-function. And return an KomichiError when a value cannot be found by the given callback-function
expand_text_with
Return the given text, containing bash-like-curly variables that are expanded with values from the given callback function.
get_cwd
Return the current user’s current working directory (“CWD”) as a Utf8PathBuf.
get_home
Return the current user’s home directory as a Utf8PathBuf.
get_local_application_paths
Return a LocalDirectories struct that has functions to get various local application paths for the given application name.
get_system_application_paths
Return a SystemDirectories struct which can be used to get system directories for a given application-name as if the application has been installed on the system but not installed locally (in the user’s home directory)
normalize_path
Return the given path with all its intermediate components normalized, without performing I/O.
scrub_path
Replace the user’s home directory, in the given path, with a tilde.
use_cwd
Return the given path or the current user’s current working directory (“CWD”) as a Utf8PathBuf.
use_home
Return the given home directory or the current user’s home directory as a Utf8PathBuf.
utf8_path_buf
Convert the given path into a Utf8PathBuf.