Crate komichi

小道 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 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.0.0

• Addition of SystemDirectories
• BREAKING CHANGES
  • komichi::error::Error has been renamed to KomichiError
  • komichi::error::ExpandError has been renamed to ExpandPathError
  • komichi::error::ExpandLexerError has been renamed to ExpandPathLexerError
  • komichi::expand_environment_identifiers has been renamed to expand_path_with_environ
  • komichi::local:Local has been renamed to LocalDirectories
  • komichi::expand_with has been renamed to expand_path_with
  • komichi::expand_strict_with has been renamed to expand_path_strict_with
  • komichi::expand_tilde has been renamed to expand_path_tilde
  • komichi::expand_cwd has been renamed to expand_path_cwd
  • komichi::normalize has been renamed to normalize_path
  • komichi::error::scrub has been moved to scrub_path

1.0.3 (2024-04-01)

• Addition of scrub_path

1.0.1 (2024-03-25)

• YANKED
• Unix bug fixes

1.0.0 (2024-03-25)

• YANKED
• Doc fixes
• Addition of EnvVal and local
• Addition of expand and normalize_path

Modules

error

Komichi errors.

Structs

EnvVal

Used to acquire an environment variable value with a fallback value.

ExpandPath

Expand identifiers in paths.

ExpandText

Provide the ability to expand BASH-like-curly-variables in text or in a file.

LocalDirectories

Provide path locations for a given application name from a local perspective.

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).

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.