- }))
+ })
}
}
-pub enum CacheFreshness {
- /// The cache is still fresh (less than `MAX_CACHE_AGE` old)
- Fresh,
- /// The cache is stale and should be updated
- Stale(Duration),
- /// The cache is missing
- Missing,
+impl Language<'_> {
+ fn directory_name(&self) -> String {
+ format!("pages.{}", self.0)
+ }
}
-impl Cache {
- pub fn new(cache_dir: P, enable_styles: bool, tls_backend: TlsBackend) -> Self
- where
- P: Into,
- {
- Self {
- cache_dir: cache_dir.into(),
- enable_styles,
- tls_backend,
- }
- }
-
- pub fn cache_dir(&self) -> &Path {
- &self.cache_dir
- }
-
- /// Make sure that the cache directory exists and is a directory.
- /// If necessary, create the directory.
- fn ensure_cache_dir_exists(&self) -> Result<()> {
- // Check whether `cache_dir` exists and is a directory
- let (cache_dir_exists, cache_dir_is_dir) = self
- .cache_dir
- .metadata()
- .map_or((false, false), |md| (true, md.is_dir()));
- ensure!(
- !cache_dir_exists || cache_dir_is_dir,
- "Cache directory path `{}` is not a directory",
- self.cache_dir.display(),
- );
-
- if !cache_dir_exists {
- // If missing, try to create the complete directory path
- fs::create_dir_all(&self.cache_dir).with_context(|| {
- format!(
- "Cache directory path `{}` cannot be created",
- self.cache_dir.display(),
- )
- })?;
- eprintln!(
- "Successfully created cache directory path `{}`.",
- self.cache_dir.display(),
- );
- }
-
- Ok(())
- }
-
- fn pages_dir(&self) -> PathBuf {
- self.cache_dir.join(TLDR_PAGES_DIR)
- }
-
- /// Update the pages cache from the specified URL.
- pub fn update(&self, archive_source: &str) -> Result<()> {
- self.ensure_cache_dir_exists()?;
-
- let archive_url = format!("{archive_source}/tldr.zip");
-
- let client = Self::build_client(self.tls_backend)?;
- // First, download the compressed data
- let bytes: Vec = Self::download(&client, &archive_url)?;
-
- // Decompress the response body into an `Archive`
- let mut archive = ZipArchive::new(Cursor::new(bytes))
- .context("Could not decompress downloaded ZIP archive")?;
-
- // Clear cache directory
- // Note: This is not the best solution. Ideally we would download the
- // archive to a temporary directory and then swap the two directories.
- // But renaming a directory doesn't work across filesystems and Rust
- // does not yet offer a recursive directory copying function. So for
- // now, we'll use this approach.
- self.clear()
- .context("Could not clear the cache directory")?;
-
- // Extract archive into pages dir
- archive
- .extract(self.pages_dir())
- .context("Could not unpack compressed data")?;
-
- Ok(())
- }
-
- /// Return the duration since the cache directory was last modified.
- pub fn last_update(&self) -> Option {
- if let Ok(metadata) = fs::metadata(self.pages_dir()) {
- if let Ok(mtime) = metadata.modified() {
- let now = SystemTime::now();
- return now.duration_since(mtime).ok();
- };
- };
- None
- }
-
- /// Return the freshness of the cache (fresh, stale or missing).
- pub fn freshness(&self) -> CacheFreshness {
- match self.last_update() {
- Some(ago) if ago > crate::config::MAX_CACHE_AGE => CacheFreshness::Stale(ago),
- Some(_) => CacheFreshness::Fresh,
- None => CacheFreshness::Missing,
- }
- }
-
- /// Return the platform directory.
- fn get_platform_dir(platform: PlatformType) -> &'static str {
- match platform {
+impl PlatformType {
+ fn directory_name(self) -> &'static str {
+ match self {
PlatformType::Linux => "linux",
PlatformType::OsX => "osx",
PlatformType::SunOs => "sunos",
@@ -202,233 +329,10 @@ impl Cache {
PlatformType::Common => "common",
}
}
-
- /// Check for pages for a given platform in one of the given languages.
- fn find_page_for_platform(
- page_name: &str,
- pages_dir: &Path,
- platform: &str,
- language_dirs: &[String],
- ) -> Option {
- language_dirs
- .iter()
- .map(|lang_dir| pages_dir.join(lang_dir).join(platform).join(page_name))
- .find(|path| path.exists() && path.is_file())
- }
-
- /// Look up custom patch (.patch.md). If it exists, store it in a variable.
- fn find_patch(patch_name: &str, custom_pages_dir: Option<&Path>) -> Option {
- custom_pages_dir
- .map(|custom_dir| custom_dir.join(patch_name))
- .filter(|path| path.exists() && path.is_file())
- }
-
- /// Search for a page and return the path to it.
- pub fn find_page(
- &self,
- name: &str,
- languages: &[String],
- custom_pages_dir: Option<&Path>,
- platforms: &[PlatformType],
- ) -> Option {
- let page_filename = format!("{name}.md");
- let patch_filename = format!("{name}.patch.md");
- let custom_filename = format!("{name}.page.md");
-
- // Determine directory paths
- let pages_dir = self.pages_dir();
- let lang_dirs: Vec = languages
- .iter()
- .map(|lang| {
- if lang == "en" {
- String::from("pages")
- } else {
- format!("pages.{lang}")
- }
- })
- .collect();
-
- // Look up custom page (.page.md). If it exists, return it directly
- if let Some(config_dir) = custom_pages_dir {
- // TODO: Remove this check 1 year after version 1.7.0 was released
- self.check_for_old_custom_pages(config_dir);
-
- let custom_page = config_dir.join(custom_filename);
- if custom_page.exists() && custom_page.is_file() {
- return Some(PageLookupResult::with_page(custom_page));
- }
- }
-
- let patch_path = Self::find_patch(&patch_filename, custom_pages_dir);
-
- // Try to find a platform specific path next, in the order supplied by the user, and append custom patch to it.
- for &platform in platforms {
- let platform_dir = Cache::get_platform_dir(platform);
- if let Some(page) =
- Self::find_page_for_platform(&page_filename, &pages_dir, platform_dir, &lang_dirs)
- {
- return Some(PageLookupResult::with_page(page).with_optional_patch(patch_path));
- }
- }
-
- None
- }
-
- /// Return the available pages.
- pub fn list_pages(
- &self,
- custom_pages_dir: Option<&Path>,
- platforms: &[PlatformType],
- ) -> Vec {
- // Determine platforms directory and platform
- let platforms_dir = self.pages_dir().join("pages");
- let platform_dirs: Vec<&'static str> = platforms
- .iter()
- .map(|&p| Self::get_platform_dir(p))
- .collect();
-
- // Closure that allows the WalkDir instance to traverse platform
- // relevant page directories, but not others.
- let should_walk = |entry: &DirEntry| -> bool {
- let file_type = entry.file_type();
- let Some(file_name) = entry.file_name().to_str() else {
- return false;
- };
- if file_type.is_dir() {
- return platform_dirs.contains(&file_name);
- } else if file_type.is_file() {
- return true;
- }
- false
- };
-
- let to_stem = |entry: DirEntry| -> Option {
- entry
- .path()
- .file_stem()
- .and_then(OsStr::to_str)
- .map(str::to_string)
- };
-
- let to_stem_custom = |entry: DirEntry| -> Option {
- entry
- .path()
- .file_name()
- .and_then(OsStr::to_str)
- .and_then(|s| s.strip_suffix(".page.md"))
- .map(str::to_string)
- };
-
- // Recursively walk through platform specific directory
- let mut pages = WalkDir::new(platforms_dir)
- .min_depth(1) // Skip root directory
- .into_iter()
- .filter_entry(should_walk) // Filter out pages for other architectures
- .filter_map(Result::ok) // Convert results to options, filter out errors
- .filter_map(|e| {
- let extension = e.path().extension().unwrap_or_default();
- if e.file_type().is_file() && extension == "md" {
- to_stem(e)
- } else {
- None
- }
- })
- .collect::>();
-
- if let Some(custom_pages_dir) = custom_pages_dir {
- let is_page = |entry: &DirEntry| -> bool {
- entry.file_type().is_file()
- && entry
- .path()
- .file_name()
- .and_then(OsStr::to_str)
- .is_some_and(|file_name| file_name.ends_with(".page.md"))
- };
-
- let custom_pages = WalkDir::new(custom_pages_dir)
- .min_depth(1)
- .max_depth(1)
- .into_iter()
- .filter_entry(is_page)
- .filter_map(Result::ok)
- .filter_map(to_stem_custom);
-
- pages.extend(custom_pages);
- }
-
- pages.sort();
- pages.dedup();
- pages
- }
-
- /// Delete the cache directory
- ///
- /// Returns true if the cache was deleted and false if the cache dir did
- /// not exist.
- pub fn clear(&self) -> Result {
- if !self.cache_dir.exists() {
- return Ok(false);
- }
- ensure!(
- self.cache_dir.is_dir(),
- "Cache path ({}) is not a directory.",
- self.cache_dir.display(),
- );
-
- // Delete old tldr-pages cache location as well if present
- // TODO: To be removed in the future
- for pages_dir_name in [TLDR_PAGES_DIR, TLDR_OLD_PAGES_DIR] {
- let pages_dir = self.cache_dir.join(pages_dir_name);
-
- if pages_dir.exists() {
- fs::remove_dir_all(&pages_dir).with_context(|| {
- format!(
- "Could not remove the cache directory at {}",
- pages_dir.display()
- )
- })?;
- }
- }
-
- Ok(true)
- }
-
- /// Check for old custom pages (without .md suffix) and print a warning.
- fn check_for_old_custom_pages(&self, custom_pages_dir: &Path) {
- let old_custom_pages_exist = WalkDir::new(custom_pages_dir)
- .min_depth(1)
- .max_depth(1)
- .into_iter()
- .filter_entry(|entry| entry.file_type().is_file())
- .any(|entry| {
- if let Ok(entry) = entry {
- let extension = entry.path().extension();
- if let Some(extension) = extension {
- extension == "page" || extension == "patch"
- } else {
- false
- }
- } else {
- false
- }
- });
- if old_custom_pages_exist {
- print_warning(
- self.enable_styles,
- &format!(
- "Custom pages using the old naming convention were found in {}.\n\
- Please rename them to follow the new convention:\n\
- - `.page` → `.page.md`\n\
- - `.patch` → `.patch.md`",
- custom_pages_dir.display()
- ),
- );
- }
- }
}
-impl Cache {
- fn build_client(tls_backend: TlsBackend) -> Result {
+impl Cache<'_> {
+ fn build_client(tls_backend: TlsBackend) -> Agent {
let tls_builder = match tls_backend {
#[cfg(feature = "native-tls")]
TlsBackend::NativeTls => TlsConfig::builder()
@@ -444,22 +348,29 @@ impl Cache {
.root_certs(RootCerts::PlatformVerifier),
};
let config = Agent::config_builder()
+ .http_status_as_error(false) // because we want to handle them
.tls_config(tls_builder.build())
.build();
- Ok(config.into())
+ config.into()
}
/// Download the archive from the specified URL.
- fn download(client: &Agent, archive_url: &str) -> Result> {
- let response = client
- .get(archive_url)
- .call()
- .with_context(|| format!("Could not download tldr pages from {archive_url}"))?;
- let mut buf: Vec = Vec::new();
- response.into_body().into_reader().read_to_end(&mut buf)?;
- debug!("{} bytes downloaded", buf.len());
- Ok(buf)
+ fn download(client: &Agent, archive_url: &str) -> Result>> {
+ info!("Downloading archive from {archive_url}");
+ let response = client.get(archive_url).call();
+ match response {
+ Ok(response) if response.status().is_success() => {
+ let mut buf: Vec = Vec::new();
+ response.into_body().into_reader().read_to_end(&mut buf)?;
+ debug!("{} bytes downloaded", buf.len());
+ Ok(Some(buf))
+ }
+ Ok(response) if response.status() == StatusCode::NOT_FOUND => Ok(None),
+ _ => {
+ bail!("Could not download tldr pages from {archive_url}: {response:?}")
+ }
+ }
}
}
@@ -517,22 +428,4 @@ mod tests {
assert_eq!(&buf, b"Hello\n");
}
-
- #[test]
- #[cfg(feature = "native-tls")]
- fn test_create_https_client_with_native_tls() {
- Cache::build_client(TlsBackend::NativeTls).expect("fails to build a client.");
- }
-
- #[test]
- #[cfg(feature = "rustls-with-webpki-roots")]
- fn test_create_https_client_with_rustls() {
- Cache::build_client(TlsBackend::RustlsWithWebpkiRoots).expect("fails to build a client.");
- }
-
- #[test]
- #[cfg(feature = "rustls-with-native-roots")]
- fn test_create_https_client_with_rustls_with_native_roots() {
- Cache::build_client(TlsBackend::RustlsWithNativeRoots).expect("fails to build a client.");
- }
}
diff --git a/src/cli.rs b/src/cli.rs
index 0ba9de9..8270a8f 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -2,7 +2,7 @@
use std::path::PathBuf;
-use clap::{arg, builder::ArgAction, command, ArgGroup, Parser};
+use clap::{ArgGroup, Parser, builder::ArgAction};
use crate::types::{ColorOptions, PlatformType};
@@ -18,7 +18,9 @@ use crate::types::{ColorOptions, PlatformType};
{usage-heading} {usage}
{all-args}{after-help}",
- after_help = "To view the user documentation, please visit https://tealdeer-rs.github.io/tealdeer/.",
+ after_help = "To view the user documentation, please visit https://docs.tealdeer.org.
+
+To view usage examples, run tldr tldr or tldr tealdeer.",
arg_required_else_help = true,
help_expected = true,
group = ArgGroup::new("command_or_file").args(&["command", "render"]),
@@ -67,13 +69,21 @@ pub(crate) struct Cli {
pub update: bool,
/// If auto update is configured, disable it for this run
- #[arg(long = "no-auto-update", requires = "command_or_file")]
+ #[arg(long = "no-auto-update")]
pub no_auto_update: bool,
/// Clear the local cache
#[arg(short = 'c', long = "clear-cache")]
pub clear_cache: bool,
+ /// Override config file location
+ #[arg(long = "config-path", value_name = "FILE")]
+ pub config_path: Option,
+
+ /// Override config values after reading config file (example: `updates.auto_update = true`)
+ #[arg(long, action = ArgAction::Append, value_name = "OVERRIDE")]
+ pub override_config: Vec,
+
/// Use a pager to page output
#[arg(long = "pager", requires = "command_or_file")]
pub pager: bool,
@@ -98,6 +108,14 @@ pub(crate) struct Cli {
#[arg(long = "color", value_name = "WHEN")]
pub color: Option,
+ /// Display the short variants of placeholders
+ #[arg(long)]
+ pub short_options: bool,
+
+ /// Display the long variants of placeholders
+ #[arg(long)]
+ pub long_options: bool,
+
/// Print the version
// Note: We override the version flag because clap uses `-V` by default,
// while TLDR specification requires `-v` to be used.
diff --git a/src/config.rs b/src/config.rs
index 3d82eea..ec84984 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -1,18 +1,26 @@
use std::{
- env, fmt, fs,
- io::{Read, Write},
- path::{Path, PathBuf},
+ borrow::Cow,
+ env, fmt,
+ fs::{self, File},
+ io::{ErrorKind, Write},
+ path::{Component, Path, PathBuf},
+ str::FromStr,
+ sync::LazyLock,
time::Duration,
};
-use anyhow::{anyhow, bail, ensure, Context, Result};
-use app_dirs::{get_app_root, AppDataType};
-use log::debug;
+use anyhow::{Context, Result, anyhow, bail, ensure};
+use clap::ValueEnum;
+use log::info;
use serde::Serialize as _;
use serde_derive::{Deserialize, Serialize};
+use toml::map::Map;
use yansi::{Color, Style};
-use crate::types::PathSource;
+use crate::{
+ extensions::Dedup as _,
+ types::{PathSource, PlatformType},
+};
pub const CONFIG_FILE_NAME: &str = "config.toml";
pub const MAX_CACHE_AGE: Duration = Duration::from_secs(2_592_000); // 30 days
@@ -26,10 +34,70 @@ const SUPPORTED_TLS_BACKENDS: &[RawTlsBackend] = &[
RawTlsBackend::RustlsWithNativeRoots,
];
+struct SystemDirectories {
+ config: PathBuf,
+ cache: PathBuf,
+ data: PathBuf,
+}
+
+impl SystemDirectories {
+ fn discover() -> Result {
+ use etcetera::{
+ AppStrategy, AppStrategyArgs, app_strategy::choose_native_strategy, choose_app_strategy,
+ };
+
+ let args = AppStrategyArgs {
+ top_level_domain: String::new(),
+ author: String::new(),
+ app_name: crate::NAME.to_string(),
+ };
+
+ // The app strategy prefers XDG on MacOs, whereas the native strategy returns paths which
+ // are used by installed applications. On Linux and Windows, the strategies are the same.
+ let app_dirs = choose_app_strategy(args.clone())?;
+ let native_dirs = choose_native_strategy(args)?;
+
+ // We prefer the XDG paths, but before tealdeer 1.9, we used only the native paths on MacOs.
+ // So if we find files in these locations, we keep using them.
+ let fallback = |app_dir: PathBuf, native_dir: PathBuf| {
+ if !app_dir.exists() && native_dir.exists() {
+ native_dir
+ } else {
+ app_dir
+ }
+ };
+
+ Ok(Self {
+ config: fallback(app_dirs.config_dir(), native_dirs.config_dir()),
+ cache: fallback(app_dirs.cache_dir(), native_dirs.cache_dir()),
+ data: fallback(app_dirs.data_dir(), native_dirs.data_dir()),
+ })
+ }
+}
+static SYSTEM_DIRECTORIES: LazyLock = LazyLock::new(|| {
+ SystemDirectories::discover().expect("Failed to initialize system directories.")
+});
+
+pub(crate) fn supported_tls_backends_string() -> String {
+ SUPPORTED_TLS_BACKENDS
+ .iter()
+ .map(std::string::ToString::to_string)
+ .collect::>()
+ .join(", ")
+}
+
fn default_underline() -> bool {
false
}
+const fn default_base_indent() -> usize {
+ 2
+}
+
+const fn default_command_indent() -> usize {
+ 6
+}
+
fn default_bold() -> bool {
false
}
@@ -138,8 +206,8 @@ struct RawStyleConfig {
pub example_variable: RawStyle,
}
-impl From for StyleConfig {
- fn from(raw_style_config: RawStyleConfig) -> Self {
+impl From<&RawStyleConfig> for StyleConfig {
+ fn from(raw_style_config: &RawStyleConfig) -> Self {
Self {
command_name: raw_style_config.command_name.into(),
description: raw_style_config.description.into(),
@@ -156,13 +224,57 @@ struct RawDisplayConfig {
pub compact: bool,
#[serde(default)]
pub use_pager: bool,
+ #[serde(default)]
+ pub show_title: bool,
+ #[serde(default)]
+ pub indent: RawIndent,
+ #[serde(default)]
+ pub placeholder_format: PlaceholderFormat,
}
-impl From for DisplayConfig {
- fn from(raw_display_config: RawDisplayConfig) -> Self {
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+struct RawIndent {
+ #[serde(default = "default_base_indent")]
+ base: usize,
+ #[serde(default = "default_command_indent")]
+ command: usize,
+}
+
+impl Default for RawIndent {
+ fn default() -> Self {
+ Self {
+ base: 2,
+ command: 6,
+ }
+ }
+}
+
+impl From for Indent {
+ fn from(raw_indent: RawIndent) -> Self {
+ Self {
+ base: raw_indent.base,
+ command: raw_indent.command,
+ }
+ }
+}
+
+#[derive(Debug, Copy, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum PlaceholderFormat {
+ Short,
+ #[default]
+ Long,
+ Both,
+}
+
+impl From<&RawDisplayConfig> for DisplayConfig {
+ fn from(raw_display_config: &RawDisplayConfig) -> Self {
Self {
compact: raw_display_config.compact,
use_pager: raw_display_config.use_pager,
+ show_title: raw_display_config.show_title,
+ indent: raw_display_config.indent.into(),
+ placeholder_format: raw_display_config.placeholder_format,
}
}
}
@@ -176,7 +288,18 @@ const fn default_auto_update_interval_hours() -> u64 {
}
fn default_archive_source() -> String {
- "https://github.com/tldr-pages/tldr/releases/latest/download/".to_owned()
+ "https://github.com/tldr-pages/tldr/releases/latest/download".to_owned()
+}
+
+/// Controls when a warning about an outdated cache is printed.
+///
+/// Currently, the only nameable option is `"never"`. In the future, this may
+/// be extended to also accept a duration (e.g. `"60d"`), after which the
+/// warning should be shown.
+#[derive(Copy, Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+enum RawWarnCacheAge {
+ Never,
}
#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
@@ -189,6 +312,10 @@ struct RawUpdatesConfig {
pub archive_source: String,
#[serde(default)]
pub tls_backend: RawTlsBackend,
+ #[serde(default)]
+ pub download_languages: Option>,
+ #[serde(default)]
+ pub warn_cache_age: Option,
}
impl Default for RawUpdatesConfig {
@@ -198,41 +325,12 @@ impl Default for RawUpdatesConfig {
auto_update_interval_hours: DEFAULT_UPDATE_INTERVAL_HOURS,
archive_source: default_archive_source(),
tls_backend: RawTlsBackend::default(),
+ download_languages: None,
+ warn_cache_age: None,
}
}
}
-impl TryFrom for UpdatesConfig {
- type Error = anyhow::Error;
-
- fn try_from(raw_updates_config: RawUpdatesConfig) -> Result {
- let tls_backend = match raw_updates_config.tls_backend {
- #[cfg(feature = "native-tls")]
- RawTlsBackend::NativeTls => TlsBackend::NativeTls,
- #[cfg(feature = "rustls-with-webpki-roots")]
- RawTlsBackend::RustlsWithWebpkiRoots => TlsBackend::RustlsWithWebpkiRoots,
- #[cfg(feature = "rustls-with-native-roots")]
- RawTlsBackend::RustlsWithNativeRoots => TlsBackend::RustlsWithNativeRoots,
- // when compiling without all TLS backend features, we want to handle config error.
- #[allow(unreachable_patterns)]
- _ => return Err(anyhow!(
- "Unsupported TLS backend: {}. This tealdeer build has support for the following options: {}",
- raw_updates_config.tls_backend,
- SUPPORTED_TLS_BACKENDS.iter().map(std::string::ToString::to_string).collect::>().join(", ")
- ))
- };
-
- Ok(Self {
- auto_update: raw_updates_config.auto_update,
- auto_update_interval: Duration::from_secs(
- raw_updates_config.auto_update_interval_hours * 3600,
- ),
- archive_source: raw_updates_config.archive_source,
- tls_backend,
- })
- }
-}
-
#[derive(Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
struct RawDirectoriesConfig {
#[serde(default)]
@@ -241,6 +339,63 @@ struct RawDirectoriesConfig {
pub custom_pages_dir: Option,
}
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+enum RawPlatformType {
+ Current,
+ All,
+ MacOs, // alias for Platform(PlatformType::OsX)
+ #[serde(untagged)]
+ Platform(PlatformType),
+}
+
+impl RawPlatformType {
+ pub fn flatten(raw_platforms: impl IntoIterator- ) -> Vec {
+ let mut flattened = Vec::new();
+ for raw_platform in raw_platforms {
+ match raw_platform {
+ RawPlatformType::Current => flattened.push(PlatformType::current()),
+ RawPlatformType::Platform(platform) => flattened.push(platform),
+ RawPlatformType::MacOs => flattened.push(PlatformType::OsX),
+ RawPlatformType::All => flattened.extend(PlatformType::value_variants()),
+ }
+ }
+ flattened.clear_duplicates();
+ flattened
+ }
+}
+
+#[derive(Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
+struct RawSearchConfig {
+ pub languages: Option>,
+ pub platforms: Option>,
+}
+
+impl<'a> From<&'a RawSearchConfig> for SearchConfig<'a> {
+ fn from(raw_search_config: &'a RawSearchConfig) -> Self {
+ let languages = raw_search_config
+ .languages
+ .as_ref()
+ .map_or_else(get_languages_from_env, |langs| {
+ langs.iter().map(|lang| Language(lang)).collect()
+ });
+ let platforms = if let Some(raw_platforms) = raw_search_config.platforms.as_ref() {
+ RawPlatformType::flatten(raw_platforms.iter().copied())
+ } else {
+ RawPlatformType::flatten([
+ RawPlatformType::Current,
+ RawPlatformType::Platform(PlatformType::Common),
+ RawPlatformType::All,
+ ])
+ };
+
+ Self {
+ languages,
+ platforms,
+ }
+ }
+}
+
#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(default)]
struct RawConfig {
@@ -248,12 +403,7 @@ struct RawConfig {
display: RawDisplayConfig,
updates: RawUpdatesConfig,
directories: RawDirectoriesConfig,
-}
-
-impl RawConfig {
- fn new() -> Self {
- Self::default()
- }
+ search: RawSearchConfig,
}
impl Default for RawConfig {
@@ -263,6 +413,7 @@ impl Default for RawConfig {
display: RawDisplayConfig::default(),
updates: RawUpdatesConfig::default(),
directories: RawDirectoriesConfig::default(),
+ search: RawSearchConfig::default(),
};
// Set default config
@@ -276,7 +427,7 @@ impl Default for RawConfig {
}
}
-#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+#[derive(Copy, Clone, Default, Debug, PartialEq, Eq)]
pub struct StyleConfig {
pub description: Style,
pub command_name: Style,
@@ -289,14 +440,25 @@ pub struct StyleConfig {
pub struct DisplayConfig {
pub compact: bool,
pub use_pager: bool,
+ pub show_title: bool,
+ pub indent: Indent,
+ pub placeholder_format: PlaceholderFormat,
+}
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub struct Indent {
+ pub base: usize,
+ pub command: usize,
}
#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct UpdatesConfig {
+pub struct UpdatesConfig<'a> {
pub auto_update: bool,
pub auto_update_interval: Duration,
- pub archive_source: String,
+ pub archive_source: &'a str,
pub tls_backend: TlsBackend,
+ pub download_languages: Vec>,
+ pub warn_cache_age: Option,
}
#[derive(Clone, Debug, PartialEq, Eq)]
@@ -323,6 +485,60 @@ pub struct DirectoriesConfig {
pub custom_pages_dir: Option,
}
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SearchConfig<'a> {
+ pub languages: Vec>,
+ pub platforms: Vec,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct Language<'a>(pub &'a str);
+
+fn get_languages<'a>(
+ env_lang: Option<&'a str>,
+ env_language: Option<&'a str>,
+) -> Vec> {
+ // Language list according to
+ // https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md#language
+
+ let Some(env_lang) = env_lang else {
+ return vec![Language("en")];
+ };
+
+ // Create an iterator that contains $LANGUAGE (':' separated list) followed by $LANG (single language)
+ let locales = env_language.unwrap_or("").split(':').chain([env_lang]);
+
+ let mut lang_list = Vec::new();
+ for locale in locales {
+ if !locale.is_ascii() {
+ info!("Skipping non-ASCII locale string: {locale}");
+ continue;
+ }
+
+ // Language plus country code (e.g. `en_US`)
+ if locale.len() >= 5 && locale.chars().nth(2) == Some('_') {
+ lang_list.push(Language(&locale[..5]));
+ }
+ // Language code only (e.g. `en`)
+ if locale.len() >= 2 && locale != "POSIX" {
+ lang_list.push(Language(&locale[..2]));
+ }
+ }
+
+ lang_list.push(Language("en"));
+ lang_list.clear_duplicates();
+ lang_list
+}
+
+pub fn get_languages_from_env<'a>() -> Vec> {
+ static LANG: LazyLock> = LazyLock::new(|| std::env::var("LANG").ok());
+ static LANGUAGE: LazyLock> = LazyLock::new(|| std::env::var("LANGUAGE").ok());
+ get_languages(
+ LANG.as_ref().map(String::as_str),
+ LANGUAGE.as_ref().map(String::as_str),
+ )
+}
+
#[derive(Copy, Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum RawTlsBackend {
@@ -360,23 +576,89 @@ pub enum TlsBackend {
RustlsWithNativeRoots,
}
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct Config {
- pub style: StyleConfig,
- pub display: DisplayConfig,
- pub updates: UpdatesConfig,
- pub directories: DirectoriesConfig,
+impl TryFrom for TlsBackend {
+ type Error = anyhow::Error;
+
+ fn try_from(raw: RawTlsBackend) -> Result {
+ match raw {
+ #[cfg(feature = "native-tls")]
+ RawTlsBackend::NativeTls => Ok(TlsBackend::NativeTls),
+ #[cfg(feature = "rustls-with-webpki-roots")]
+ RawTlsBackend::RustlsWithWebpkiRoots => Ok(TlsBackend::RustlsWithWebpkiRoots),
+ #[cfg(feature = "rustls-with-native-roots")]
+ RawTlsBackend::RustlsWithNativeRoots => Ok(TlsBackend::RustlsWithNativeRoots),
+ // when compiling without all TLS backend features, we want to handle config error.
+ #[allow(unreachable_patterns)]
+ _ => Err(anyhow!(
+ "Unsupported TLS backend: {}. This tealdeer build has support for the following options: {}",
+ raw,
+ supported_tls_backends_string(),
+ )),
+ }
+ }
}
-impl Config {
+impl TlsBackend {
+ const fn as_raw(self) -> RawTlsBackend {
+ match self {
+ #[cfg(feature = "native-tls")]
+ Self::NativeTls => RawTlsBackend::NativeTls,
+ #[cfg(feature = "rustls-with-webpki-roots")]
+ Self::RustlsWithWebpkiRoots => RawTlsBackend::RustlsWithWebpkiRoots,
+ #[cfg(feature = "rustls-with-native-roots")]
+ Self::RustlsWithNativeRoots => RawTlsBackend::RustlsWithNativeRoots,
+ }
+ }
+}
+
+impl fmt::Display for TlsBackend {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ self.as_raw().fmt(f)
+ }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Config<'a> {
+ pub style: StyleConfig,
+ pub display: DisplayConfig,
+ pub updates: UpdatesConfig<'a>,
+ pub directories: DirectoriesConfig,
+ pub search: SearchConfig<'a>,
+ pub file_path: PathWithSource,
+}
+
+impl<'a> Config<'a> {
/// Convert a `RawConfig` to a high-level `Config`.
///
/// For this, some values need to be converted to other types and some
/// defaults need to be set (sometimes based on env variables).
- fn from_raw(raw_config: RawConfig, relative_path_root: &Path) -> Result {
- let style = raw_config.style.into();
- let display = raw_config.display.into();
- let updates = raw_config.updates.try_into()?;
+ fn from_raw(raw_config: &'a RawConfig, config_file_path: PathWithSource) -> Result {
+ let style = (&raw_config.style).into();
+ let display = (&raw_config.display).into();
+ let search: SearchConfig<'a> = (&raw_config.search).into();
+
+ let updates = UpdatesConfig {
+ auto_update: raw_config.updates.auto_update,
+ auto_update_interval: Duration::from_secs(
+ raw_config.updates.auto_update_interval_hours * 3600,
+ ),
+ archive_source: &raw_config.updates.archive_source,
+ tls_backend: raw_config.updates.tls_backend.try_into()?,
+ download_languages: raw_config.updates.download_languages.as_ref().map_or_else(
+ || search.languages.clone(),
+ |languages| languages.iter().map(|lang| Language(lang)).collect(),
+ ),
+ warn_cache_age: match raw_config.updates.warn_cache_age {
+ None => Some(MAX_CACHE_AGE),
+ Some(RawWarnCacheAge::Never) => None,
+ },
+ };
+
+ let relative_path_root = config_file_path
+ .path()
+ .parent()
+ .context("Failed to get config directory")?;
+ let home_path = env::home_dir();
// Determine directories config. For this, we need to take some
// additional factory into account, like env variables, or the
@@ -386,47 +668,51 @@ impl Config {
// For backwards compatibility reasons, the cache directory can be
// overridden using an env variable. This is deprecated and will be
// phased out in the future.
- eprintln!("Warning: The ${cache_dir_env_var} env variable is deprecated, use the `cache_dir` option in the config file instead.");
+ eprintln!(
+ "Warning: The ${cache_dir_env_var} env variable is deprecated, use the `cache_dir` option in the config file instead."
+ );
PathWithSource {
path: PathBuf::from(env_var),
source: PathSource::EnvVar,
}
- } else if let Some(config_value) = raw_config.directories.cache_dir {
- // If the user explicitly configured a cache directory, use that.
+ } else if let Some(config_value) = &raw_config.directories.cache_dir {
+ // Resolve possible ~ prefixed path
+ let expanded_path = expand_home(config_value, home_path.as_deref())?;
+ // Resolve possible relative path.
+ let resolved_path = relative_path_root.join(expanded_path);
+
PathWithSource {
- // Resolve possible relative path. It would be nicer to clean up the path, but Rust stdlib
- // does not give any method for that that does not need the paths to exist.
- path: relative_path_root.join(config_value),
+ path: resolved_path,
source: PathSource::ConfigFile,
}
- } else if let Ok(default_dir) = get_app_root(AppDataType::UserCache, &crate::APP_INFO) {
- // Otherwise, fall back to the default user cache directory.
+ } else {
PathWithSource {
- path: default_dir,
+ path: SYSTEM_DIRECTORIES.cache.clone(),
source: PathSource::OsConvention,
}
- } else {
- // If everything fails, give up
- bail!("Could not determine user cache directory");
};
let custom_pages_dir = raw_config
.directories
.custom_pages_dir
- .map(|path| PathWithSource {
+ .as_ref()
+ .map(|path| -> Result {
+ // Resolve possible ~ prefixed path
+ let expanded_path = expand_home(path, home_path.as_deref())?;
// Resolve possible relative path.
- path: relative_path_root.join(path),
- source: PathSource::ConfigFile,
+ let resolved_path = relative_path_root.join(expanded_path);
+
+ Ok(PathWithSource {
+ path: resolved_path,
+ source: PathSource::ConfigFile,
+ })
})
+ .transpose()?
.or_else(|| {
- get_app_root(AppDataType::UserData, &crate::APP_INFO)
- .map(|path| {
- // Note: The `join("")` call ensures that there's a trailing slash
- PathWithSource {
- path: path.join("pages").join(""),
- source: PathSource::OsConvention,
- }
- })
- .ok()
+ // Note: The `join("")` call ensures that there's a trailing slash
+ Some(PathWithSource {
+ path: SYSTEM_DIRECTORIES.data.join("pages").join(""),
+ source: PathSource::OsConvention,
+ })
});
let directories = DirectoriesConfig {
cache_dir,
@@ -438,50 +724,136 @@ impl Config {
display,
updates,
directories,
+ search,
+ file_path: config_file_path,
})
}
+}
- pub fn load(enable_styles: bool) -> Result {
- debug!("Loading config");
+/// Expands tilde (~) prefixed directories into its absolute version
+fn expand_home<'a>(input_path: &'a Path, home_path: Option<&Path>) -> Result> {
+ let mut components = input_path.components();
- // Determine path
- let (config_file_path, _) = get_config_path().context("Could not determine config path")?;
+ if let Some(Component::Normal(first_component_raw)) = components.next() {
+ let first_component = first_component_raw
+ .to_str()
+ .ok_or(anyhow!("Path contains invalid UTF-8"))?;
- // Load raw config
- let raw_config: RawConfig = if config_file_path.exists() && config_file_path.is_file() {
- let mut config_file = fs::File::open(&config_file_path).with_context(|| {
- format!("Failed to open config file path at {:?}", &config_file_path)
- })?;
- let mut contents = String::new();
- config_file.read_to_string(&mut contents).with_context(|| {
- format!("Failed to read from config file at {:?}", &config_file_path)
- })?;
- toml::from_str(&contents).with_context(|| {
- format!("Failed to parse TOML config file at {config_file_path:?}")
- })?
- } else {
- RawConfig::new()
+ if first_component == "~" {
+ let home_path = home_path.ok_or(anyhow!("Unable to find user home directory"))?;
+ let rest: PathBuf = components.collect();
+ let expanded = home_path.join(rest);
+
+ return Ok(Cow::Owned(expanded));
+ } else if first_component.starts_with('~') {
+ return Err(anyhow!("Tilde expansion with a login name not supported"));
+ }
+ }
+
+ Ok(Cow::Borrowed(input_path))
+}
+
+/// The [`ConfigLoader`] is used to load a [`Config`] from a file.
+///
+/// Since the rich [`Config`] keeps references to [`RawConfig`], the raw config needs to be kept alive outside of the
+/// [`Config`]. The [`ConfigLoader`] thus offers the following flow:
+/// 1. Read a raw config using [`ConfigLoader::read`] or [`ConfigLoader::read_default_path`].
+/// 2. Validate the contents to a [`Config`] that borrows the [`ConfigLoader`].
+pub struct ConfigLoader {
+ raw: RawConfig,
+ path: PathWithSource,
+}
+
+impl ConfigLoader {
+ fn read_internal(
+ path: PathWithSource,
+ allow_not_found: bool,
+ overrides: &[String],
+ ) -> Result {
+ let read_raw_config = match fs::read_to_string(&path.path) {
+ Ok(content) => toml::from_str(&content).with_context(|| {
+ format!(
+ "Could not parse config file contents as toml from {}.",
+ path.path.display()
+ )
+ })?,
+ Err(e) if allow_not_found && e.kind() == ErrorKind::NotFound => RawConfig::default(),
+ Err(e) => {
+ return Err(e).context(format!(
+ "Could not read config file contents from {}.",
+ path.path().display()
+ ));
+ }
};
- // Safe to unwrap, it's a file path, so it should have a directory component
- let config_file_dir = config_file_path.parent().unwrap();
+ let read_config_table = toml::Table::try_from(read_raw_config)?;
+ let used_config_table = Self::override_config_with(read_config_table, overrides)
+ .context("Failed to apply config overrides")?;
+ let raw = used_config_table.try_into()?;
- // Convert to config, resolve relative paths from the config file dir
- let mut config =
- Self::from_raw(raw_config, config_file_dir).context("Could not process raw config")?;
+ Ok(Self { raw, path })
+ }
- // Potentially override styles
- if !enable_styles {
- config.style = StyleConfig {
- command_name: Style::default(),
- description: Style::default(),
- example_text: Style::default(),
- example_code: Style::default(),
- example_variable: Style::default(),
- };
+ fn override_config_with(
+ config_table: toml::Table,
+ overrides: &[String],
+ ) -> Result {
+ let mut config_table = toml::Value::Table(config_table);
+ for override_str in overrides {
+ let (name, value) = override_str
+ .split_once('=')
+ .ok_or(anyhow!("Invalid override-string: {override_str} (correct example: \"display.compact = true\")"))?;
+
+ let name = name.trim();
+ let value = toml::Value::from_str(value.trim())?;
+
+ let mut entry = &mut config_table;
+ for subkey in name.split('.') {
+ let toml::Value::Table(entry_table) = entry else {
+ bail!(
+ "\"{name}\" is not a valid identifier since \"{subkey}\" already refers to a value which is not a toml-Table."
+ );
+ };
+
+ entry = entry_table
+ .entry(subkey)
+ .or_insert(toml::Value::Table(Map::default()));
+ }
+
+ *entry = value;
}
- Ok(config)
+ match config_table {
+ toml::Value::Table(config_table) => Ok(config_table),
+ _ => unreachable!("root table is never modified"),
+ }
+ }
+
+ /// Create a loader that uses the config at `path`.
+ /// `overrides`: If set, overrides the default values of the config
+ pub fn read(path: PathBuf, overrides: &[String]) -> Result {
+ Self::read_internal(
+ PathWithSource {
+ path,
+ source: PathSource::Cli,
+ },
+ false,
+ overrides,
+ )
+ }
+
+ /// Create a loader that uses the default config file location. If no file is present at the default location, the
+ /// default configuration is used.
+ /// `overrides`: If set, overrides the default values of the config
+ pub fn read_default_path(overrides: &[String]) -> Result {
+ let path = get_default_config_path();
+ Self::read_internal(path, true, overrides)
+ }
+
+ /// Parse the read [`RawConfig`] into a [`Config`].
+ pub fn load(&self) -> Result> {
+ Config::from_raw(&self.raw, self.path.clone())
+ .context("Could not process raw config into rich config")
}
}
@@ -492,46 +864,50 @@ impl Config {
///
/// Note that this function does not verify whether the directory at that
/// location exists, or is a directory.
-pub fn get_config_dir() -> Result<(PathBuf, PathSource)> {
+pub fn get_config_dir() -> (PathBuf, PathSource) {
// Allow overriding the config directory by setting the
// $TEALDEER_CONFIG_DIR env variable.
if let Ok(value) = env::var("TEALDEER_CONFIG_DIR") {
- return Ok((PathBuf::from(value), PathSource::EnvVar));
- };
+ return (PathBuf::from(value), PathSource::EnvVar);
+ }
- // Otherwise, fall back to the user config directory.
- let dirs = get_app_root(AppDataType::UserConfig, &crate::APP_INFO)
- .context("Failed to determine the user config directory")?;
- Ok((dirs, PathSource::OsConvention))
+ (SYSTEM_DIRECTORIES.config.clone(), PathSource::OsConvention)
}
/// Return the path to the config file.
///
/// Note that this function does not verify whether the file at that location
/// exists, or is a file.
-pub fn get_config_path() -> Result<(PathBuf, PathSource)> {
- let (config_dir, source) = get_config_dir()?;
- let config_file_path = config_dir.join(CONFIG_FILE_NAME);
- Ok((config_file_path, source))
+pub fn get_default_config_path() -> PathWithSource {
+ let (mut path, source) = get_config_dir();
+ path.push(CONFIG_FILE_NAME);
+ PathWithSource { path, source }
}
/// Create default config file.
-pub fn make_default_config() -> Result {
- let (config_dir, _) = get_config_dir()?;
-
- // Ensure that config directory exists
- if config_dir.exists() {
- ensure!(
- config_dir.is_dir(),
- "Config directory could not be created: {} already exists but is not a directory",
- config_dir.to_string_lossy(),
- );
+/// path: Can be specified to create the config in that path instead of
+/// the default path.
+pub fn make_default_config(path: Option<&Path>) -> Result {
+ let config_file_path = if let Some(p) = path {
+ p.into()
} else {
- fs::create_dir_all(&config_dir).context("Could not create config directory")?;
- }
+ let (config_dir, _) = get_config_dir();
+
+ // Ensure that config directory exists
+ if config_dir.exists() {
+ ensure!(
+ config_dir.is_dir(),
+ "Config directory could not be created: {} already exists but is not a directory",
+ config_dir.to_string_lossy(),
+ );
+ } else {
+ fs::create_dir_all(&config_dir).context("Could not create config directory")?;
+ }
+
+ config_dir.join(CONFIG_FILE_NAME)
+ };
// Ensure that a config file doesn't get overwritten
- let config_file_path = config_dir.join(CONFIG_FILE_NAME);
ensure!(
!config_file_path.is_file(),
"A configuration file already exists at {}, no action was taken.",
@@ -540,11 +916,11 @@ pub fn make_default_config() -> Result {
// Create default config
let serialized_config =
- toml::to_string(&RawConfig::new()).context("Failed to serialize default config")?;
+ toml::to_string(&RawConfig::default()).context("Failed to serialize default config")?;
// Write default config
let mut config_file =
- fs::File::create(&config_file_path).context("Could not create config file")?;
+ File::create(&config_file_path).context("Could not create config file")?;
let _wc = config_file
.write(serialized_config.as_bytes())
.context("Could not write to config file")?;
@@ -552,28 +928,259 @@ pub fn make_default_config() -> Result {
Ok(config_file_path)
}
-#[test]
-fn test_serialize_deserialize() {
- let raw_config = RawConfig::new();
- let serialized = toml::to_string(&raw_config).unwrap();
- let deserialized: RawConfig = toml::from_str(&serialized).unwrap();
- assert_eq!(raw_config, deserialized);
-}
-
-#[test]
-fn test_relative_path_resolution() {
- let mut raw_config = RawConfig::new();
- raw_config.directories.cache_dir = Some("../cache".into());
- raw_config.directories.custom_pages_dir = Some("../custom_pages".into());
-
- let config = Config::from_raw(raw_config, Path::new("/path/to/config")).unwrap();
-
- assert_eq!(
- config.directories.cache_dir.path(),
- Path::new("/path/to/config/../cache")
- );
- assert_eq!(
- config.directories.custom_pages_dir.unwrap().path(),
- Path::new("/path/to/config/../custom_pages")
- );
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn serialize_deserialize() {
+ let raw_config = RawConfig::default();
+ let serialized = toml::to_string(&raw_config).unwrap();
+ let deserialized: RawConfig = toml::from_str(&serialized).unwrap();
+ assert_eq!(raw_config, deserialized);
+ }
+
+ #[test]
+ fn expand_path_with_valid_home() {
+ let home = Some(PathBuf::from("/foo/bar"));
+ let path_to_expand = PathBuf::from("~/baz");
+
+ assert_eq!(
+ *expand_home(&path_to_expand, home.as_deref()).unwrap(),
+ PathBuf::from("/foo/bar/baz")
+ );
+ }
+
+ #[test]
+ fn expand_path_with_absolute_path() {
+ let home = Some(PathBuf::from("/foo/bar"));
+ let dir_to_expand = PathBuf::from("/one/two");
+
+ assert_eq!(
+ *expand_home(&dir_to_expand, home.as_deref()).unwrap(),
+ dir_to_expand
+ );
+ }
+
+ #[test]
+ fn error_with_tilde_username() {
+ let home = Some(PathBuf::from("/foo/bar"));
+ let dir_to_expand = PathBuf::from("~baz/foo");
+
+ assert!(expand_home(&dir_to_expand, home.as_deref()).is_err());
+ }
+
+ #[test]
+ fn expand_tilde_in_config_file() {
+ let mut raw_config = RawConfig::default();
+ raw_config.directories.cache_dir = Some("~/my/custom_cache".into());
+ raw_config.directories.custom_pages_dir = Some("~/custom_pages".into());
+
+ let config = Config::from_raw(
+ &raw_config,
+ PathWithSource {
+ path: PathBuf::from("/path/to/config/config.toml"),
+ source: PathSource::OsConvention,
+ },
+ )
+ .unwrap();
+
+ let home_dir = env::home_dir().unwrap();
+
+ assert_eq!(
+ config.directories.cache_dir.path(),
+ home_dir.join("my/custom_cache")
+ );
+ assert_eq!(
+ config.directories.custom_pages_dir.unwrap().path(),
+ home_dir.join("custom_pages")
+ );
+ }
+
+ #[test]
+ fn relative_path_resolution() {
+ let mut raw_config = RawConfig::default();
+ raw_config.directories.cache_dir = Some("../cache".into());
+ raw_config.directories.custom_pages_dir = Some("../custom_pages".into());
+
+ let config = Config::from_raw(
+ &raw_config,
+ PathWithSource {
+ path: PathBuf::from("/path/to/config/config.toml"),
+ source: PathSource::OsConvention,
+ },
+ )
+ .unwrap();
+
+ assert_eq!(
+ config.directories.cache_dir.path(),
+ Path::new("/path/to/config/../cache")
+ );
+ assert_eq!(
+ config.directories.custom_pages_dir.unwrap().path(),
+ Path::new("/path/to/config/../custom_pages")
+ );
+ }
+
+ mod override_config {
+ use super::*;
+ use toml::Value;
+
+ fn base_config() -> toml::Table {
+ toml::Table::from_str(
+ "
+ global_value = false
+
+ [some]
+ value = 0
+
+ [some.inner]
+ value1 = 1
+ value2 = \"a string\"
+
+ [some.other]
+ value1 = 3
+ value2 = [ 1, \"text\", true ]
+ ",
+ )
+ .unwrap()
+ }
+
+ #[test]
+ fn basic() {
+ let original_config = base_config();
+ let overrides = &["some.inner.value1 = 'some text'".to_string()];
+
+ let new_config = ConfigLoader::override_config_with(original_config, overrides)
+ .expect("config should be successfully overwritten");
+
+ assert_eq!(new_config["some"]["value"], Value::Integer(0));
+ assert_eq!(
+ new_config["some"]["inner"]["value1"],
+ Value::String("some text".to_string()),
+ );
+ assert_eq!(
+ new_config["some"]["inner"]["value2"],
+ Value::String("a string".to_string()),
+ );
+ assert_eq!(new_config["some"]["other"]["value1"], Value::Integer(3));
+ assert_eq!(new_config["global_value"], Value::Boolean(false));
+ }
+
+ macro_rules! style_config_with {
+ ($config:ident, $overrides:expr) => {
+ let loader = ConfigLoader::read(
+ PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/style-config.toml"),
+ $overrides,
+ )
+ .unwrap();
+ let $config = loader.load().unwrap();
+ };
+ }
+
+ #[test]
+ fn dependent_config() {
+ style_config_with!(config, &["search.languages = ['de', 'it']".to_string()]);
+ assert_eq!(config.search.languages, [Language("de"), Language("it")]);
+ // Value is copied after override is applied
+ assert_eq!(
+ config.updates.download_languages,
+ [Language("de"), Language("it")]
+ );
+ }
+
+ #[test]
+ fn order() {
+ style_config_with!(
+ config,
+ &[
+ "display.compact = false".to_string(),
+ "display.compact = true".to_string(),
+ ]
+ );
+ assert!(config.display.compact);
+ }
+
+ #[test]
+ fn override_with_table() {
+ style_config_with!(config, &["display = {'compact' = true}".to_string()]);
+ assert!(config.display.compact);
+ assert_eq!(
+ config.display.indent,
+ RawConfig::default().display.indent.into()
+ );
+ }
+ }
+
+ mod language {
+ use super::*;
+
+ #[test]
+ fn missing_lang_env() {
+ let lang_list = get_languages(None, Some("de:fr"));
+ assert_eq!(lang_list, [Language("en")]);
+ let lang_list = get_languages(None, None);
+ assert_eq!(lang_list, [Language("en")]);
+ }
+
+ #[test]
+ fn missing_language_env() {
+ let lang_list = get_languages(Some("de"), None);
+ assert_eq!(lang_list, [Language("de"), Language("en")]);
+ }
+
+ #[test]
+ fn preference_order() {
+ let lang_list = get_languages(Some("de"), Some("fr:cn"));
+ assert_eq!(
+ lang_list,
+ [
+ Language("fr"),
+ Language("cn"),
+ Language("de"),
+ Language("en")
+ ]
+ );
+ }
+
+ #[test]
+ fn country_code_expansion() {
+ let lang_list = get_languages(Some("pt_BR"), None);
+ assert_eq!(
+ lang_list,
+ [Language("pt_BR"), Language("pt"), Language("en")]
+ );
+ }
+
+ #[test]
+ fn with_encoding() {
+ let lang_list = get_languages(Some("de_DE.UTF-8"), None);
+ assert_eq!(
+ lang_list,
+ [Language("de_DE"), Language("de"), Language("en")]
+ );
+ }
+
+ #[test]
+ fn ignore_posix_and_c() {
+ let lang_list = get_languages(Some("POSIX"), None);
+ assert_eq!(lang_list, [Language("en")]);
+ let lang_list = get_languages(Some("C"), None);
+ assert_eq!(lang_list, [Language("en")]);
+ }
+
+ #[test]
+ fn no_duplicates() {
+ let lang_list = get_languages(Some("de"), Some("fr:de:cn:de"));
+ assert_eq!(
+ lang_list,
+ [
+ Language("fr"),
+ Language("de"),
+ Language("cn"),
+ Language("en")
+ ]
+ );
+ }
+ }
}
diff --git a/src/extensions.rs b/src/extensions.rs
index 3aebfa2..e74e9f3 100644
--- a/src/extensions.rs
+++ b/src/extensions.rs
@@ -1,14 +1,14 @@
use std::mem;
/// An extension trait to clear duplicates from a collection.
-pub(crate) trait Dedup {
+pub(crate) trait Dedup {
fn clear_duplicates(&mut self);
}
/// Clear duplicates from a collection, keep the first one seen.
///
/// For small vectors, this will be faster than a `HashSet`.
-impl Dedup for Vec {
+impl Dedup for Vec {
fn clear_duplicates(&mut self) {
let orig = mem::replace(self, Vec::with_capacity(self.len()));
for item in orig {
diff --git a/src/formatter.rs b/src/formatter.rs
index 369efce..f06c098 100644
--- a/src/formatter.rs
+++ b/src/formatter.rs
@@ -2,25 +2,80 @@
use log::debug;
-use crate::{extensions::FindFrom, types::LineType};
+use crate::{config::Indent, extensions::FindFrom, types::LineType};
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, Eq)]
/// Represents a snippet from a page of a specific highlighting class.
-pub enum PageSnippet<'a> {
- CommandName(&'a str),
- Variable(&'a str),
- NormalCode(&'a str),
- Description(&'a str),
- Text(&'a str),
+pub enum PageSnippet {
+ CommandName(T),
+ Placeholder(T),
+ PlaceholderVariants { short: T, long: T },
+ NormalCode(T),
+ Description(T),
+ Text(T),
+ Title(T),
+ Indent(usize),
Linebreak,
}
-impl PageSnippet<'_> {
+#[cfg_attr(not(test), allow(dead_code))]
+impl PageSnippet {
+ pub fn map(self, f: F) -> PageSnippet
+ where
+ F: Fn(T) -> U,
+ {
+ match self {
+ PageSnippet::CommandName(s) => PageSnippet::CommandName(f(s)),
+ PageSnippet::Placeholder(s) => PageSnippet::Placeholder(f(s)),
+ PageSnippet::PlaceholderVariants { short, long } => PageSnippet::PlaceholderVariants {
+ short: f(short),
+ long: f(long),
+ },
+ PageSnippet::NormalCode(s) => PageSnippet::NormalCode(f(s)),
+ PageSnippet::Description(s) => PageSnippet::Description(f(s)),
+ PageSnippet::Text(s) => PageSnippet::Text(f(s)),
+ PageSnippet::Title(s) => PageSnippet::Title(f(s)),
+ PageSnippet::Indent(n) => PageSnippet::Indent(n),
+ PageSnippet::Linebreak => PageSnippet::Linebreak,
+ }
+ }
+}
+
+impl, U> PartialEq> for PageSnippet {
+ fn eq(&self, other: &PageSnippet) -> bool {
+ match (self, other) {
+ (PageSnippet::CommandName(s), PageSnippet::CommandName(t))
+ | (PageSnippet::Placeholder(s), PageSnippet::Placeholder(t))
+ | (PageSnippet::NormalCode(s), PageSnippet::NormalCode(t))
+ | (PageSnippet::Description(s), PageSnippet::Description(t))
+ | (PageSnippet::Text(s), PageSnippet::Text(t))
+ | (PageSnippet::Title(s), PageSnippet::Title(t)) => s == t,
+ (
+ PageSnippet::PlaceholderVariants {
+ short: left_short,
+ long: left_long,
+ },
+ PageSnippet::PlaceholderVariants {
+ short: right_short,
+ long: right_long,
+ },
+ ) => left_short == right_short && left_long == right_long,
+ (PageSnippet::Indent(n), PageSnippet::Indent(m)) => n == m,
+ (PageSnippet::Linebreak, PageSnippet::Linebreak) => true,
+ _ => false,
+ }
+ }
+}
+
+impl PageSnippet<&str> {
pub fn is_empty(&self) -> bool {
use PageSnippet::*;
match self {
- CommandName(s) | Variable(s) | NormalCode(s) | Description(s) | Text(s) => s.is_empty(),
+ CommandName(s) | Placeholder(s) | NormalCode(s) | Description(s) | Text(s)
+ | Title(s) => s.is_empty(),
+ PageSnippet::PlaceholderVariants { short, long } => short.is_empty() && long.is_empty(),
+ Indent(n) => *n == 0,
Linebreak => false,
}
}
@@ -31,10 +86,12 @@ pub fn highlight_lines(
lines: L,
process_snippet: &mut F,
keep_empty_lines: bool,
+ show_title: bool,
+ indent: Indent,
) -> Result<(), E>
where
L: Iterator
- ,
- F: for<'snip> FnMut(PageSnippet<'snip>) -> Result<(), E>,
+ F: for<'snip> FnMut(PageSnippet<&'snip str>) -> Result<(), E>,
{
let mut command = String::new();
for line in lines {
@@ -45,51 +102,131 @@ where
}
}
LineType::Title(title) => {
- debug!("Ignoring title");
-
+ if show_title {
+ process_snippet(PageSnippet::Linebreak)?;
+ process_snippet(PageSnippet::Indent(indent.base))?;
+ process_snippet(PageSnippet::Title(&title))?;
+ process_snippet(PageSnippet::Linebreak)?;
+ } else {
+ debug!("Ignoring title");
+ }
// This is safe as long as the parsed title is only the command,
// and the iterator yields values in order of appearance.
command = title;
- debug!("Detected command name: {}", &command);
+ debug!("Detected command name: {command}");
+ }
+ LineType::Description(text) => {
+ process_snippet(PageSnippet::Indent(indent.base))?;
+ process_snippet(PageSnippet::Description(&text))?;
+ process_snippet(PageSnippet::Linebreak)?;
+ }
+ LineType::ExampleText(text) => {
+ process_snippet(PageSnippet::Indent(indent.base))?;
+ process_snippet(PageSnippet::Text(&text))?;
+ process_snippet(PageSnippet::Linebreak)?;
}
- LineType::Description(text) => process_snippet(PageSnippet::Description(&text))?,
- LineType::ExampleText(text) => process_snippet(PageSnippet::Text(&text))?,
LineType::ExampleCode(text) => {
- process_snippet(PageSnippet::NormalCode(" "))?;
+ process_snippet(PageSnippet::Indent(indent.command))?;
highlight_code(&command, &text, process_snippet)?;
process_snippet(PageSnippet::Linebreak)?;
}
- LineType::Other(text) => debug!("Unknown line type: {:?}", text),
+ LineType::Other(text) => debug!("Unknown line type: {text:?}"),
}
}
process_snippet(PageSnippet::Linebreak)?;
Ok(())
}
-/// Highlight code examples including user variables in {{ curly braces }}.
-fn highlight_code<'a, E>(
- command: &'a str,
- text: &'a str,
- process_snippet: &mut impl FnMut(PageSnippet<'a>) -> Result<(), E>,
+/// Highlight code examples.
+/// - parse placeholders (`{{ curly braces }}`)
+/// - replace escaped placeholder markers (`\{\{` and `\}\}`)
+fn highlight_code(
+ command: &str,
+ mut text: &str,
+ process_snippet: &mut impl FnMut(PageSnippet<&str>) -> Result<(), E>,
) -> Result<(), E> {
- let variable_splits = text
- .split("}}")
- .map(|s| s.split_once("{{").unwrap_or((s, "")));
- for (code_segment, variable) in variable_splits {
- highlight_code_segment(command, code_segment, process_snippet)?;
- process_snippet(PageSnippet::Variable(variable))?;
+ // We replace escaped placeholder markers at the end so that our replacing does not interfere
+ // with finding the actual markers.
+ // NOTE: This is not optimal, as it allocates one String for each `replace`
+ let replace_escaped = |s: &str| s.replace(r"\{\{", "{{").replace(r"\}\}", "}}");
+
+ loop {
+ // Find placeholder markers and split into code and placeholder accordingly
+
+ let Some(start_marker) = find_marker(text, "{{", r"\{\{") else {
+ break;
+ };
+ let Some(mut end_marker) = find_marker(&text[start_marker + 2..], "}}", r"\}\}") else {
+ break;
+ };
+ end_marker += start_marker + 2;
+
+ // Greedily extend matched range
+ while end_marker + 2 < text.len() && text.as_bytes()[end_marker + 2] == b'}' {
+ end_marker += 1;
+ }
+
+ let placeholder_content = &text[start_marker + 2..end_marker];
+
+ if start_marker > 0 {
+ highlight_code_segment(
+ command,
+ &replace_escaped(&text[..start_marker]),
+ process_snippet,
+ )?;
+ }
+
+ let placeholder_content = replace_escaped(placeholder_content);
+ if let Some(s) = placeholder_content.strip_prefix('[')
+ && let Some(s) = s.strip_suffix(']')
+ && let Some((short, long)) = s.split_once('|')
+ {
+ process_snippet(PageSnippet::PlaceholderVariants { short, long })?;
+ } else {
+ process_snippet(PageSnippet::Placeholder(&placeholder_content))?;
+ }
+
+ text = &text[end_marker + 2..];
}
+
+ if !text.is_empty() {
+ highlight_code_segment(command, &replace_escaped(text), process_snippet)?;
+ }
+
Ok(())
}
+/// Find a "{{" (or "}}") substring that does not overlap with a preceding "\{\{" (or "\}\}").
+fn find_marker(s: &str, marker: &str, forbidden_prefix: &str) -> Option {
+ let mut search_start = 0;
+ loop {
+ let marker_index = s.find_from(marker, search_start)?;
+
+ let overlaps_with_prefix = (forbidden_prefix.len() <= marker_index + 1) && {
+ let prefix_start = marker_index + 1 - forbidden_prefix.len();
+ // NOTE: The indices might not be valid character offsets, so we should do this
+ // comparison on raw bytes. If prefix_start is indeed not a character offset than the
+ // comparison is guaranteed to return false because forbidden_prefix[0] definitely _is_
+ // the start of a (single byte, ASCII) character.
+ &s.as_bytes()[prefix_start..=marker_index] == forbidden_prefix.as_bytes()
+ };
+ if !overlaps_with_prefix {
+ return Some(marker_index);
+ }
+
+ // The next valid marker cannot include the first character of the current match
+ search_start = marker_index + 1;
+ }
+}
+
/// Yields `NormalCode` and `CommandName` in alternating order according to the occurrences of
-/// `command_name` in `segment`. Variables are not detected here, see `highlight_code`
+/// `command_name` in `segment`. Placeholders are not detected here, see `highlight_code`
/// instead.
fn highlight_code_segment<'a, E>(
command_name: &'a str,
mut segment: &'a str,
- process_snippet: &mut impl FnMut(PageSnippet<'a>) -> Result<(), E>,
+ process_snippet: &mut impl FnMut(PageSnippet<&'a str>) -> Result<(), E>,
) -> Result<(), E> {
if !command_name.is_empty() {
let mut search_start = 0;
@@ -119,20 +256,17 @@ fn is_freestanding_substring(surrounding: &str, substring: (usize, usize)) -> bo
let char_before_is_okay = surrounding[..start]
.chars()
.last()
- .filter(|prev_char| !prev_char.is_whitespace())
- .is_none();
+ .is_none_or(char::is_whitespace);
let char_after_is_okay = surrounding[end..]
.chars()
.next()
- .filter(|next_char| !next_char.is_whitespace())
- .is_none();
+ .is_none_or(char::is_whitespace);
char_before_is_okay && char_after_is_okay
}
#[cfg(test)]
mod tests {
use super::*;
- use PageSnippet::*;
#[test]
fn test_is_freestanding_substring() {
@@ -159,80 +293,251 @@ mod tests {
));
}
- fn run<'a>(cmd: &'a str, segment: &'a str) -> Vec> {
+ fn run<'a>(cmd: &'a str, segment: &'a str) -> Vec> {
let mut yielded = Vec::new();
- let mut process_snippet = |snip: PageSnippet<'a>| {
+ let mut process_snippet = |snip: PageSnippet<&str>| {
if !snip.is_empty() {
- yielded.push(snip);
+ yielded.push(snip.map(str::to_string));
}
Ok::<(), ()>(())
};
- highlight_code_segment(cmd, segment, &mut process_snippet)
- .expect("highlight code segment failed");
+ highlight_code(cmd, segment, &mut process_snippet).expect("highlight code segment failed");
yielded
}
- #[test]
- fn test_highlight_code_segment() {
- assert!(run("make", "").is_empty());
- assert_eq!(
- &run("make", "make all CC=clang -q"),
- &[CommandName("make"), NormalCode(" all CC=clang -q")]
- );
- assert_eq!(
- &run("make", " make money --always-make"),
- &[
- NormalCode(" "),
- CommandName("make"),
- NormalCode(" money --always-make")
- ]
- );
- assert_eq!(
- &run("git commit", "git commit -m 'git commit'"),
- &[CommandName("git commit"), NormalCode(" -m 'git commit'"),]
- );
+ mod highlight_code_segment {
+ use super::*;
+ use PageSnippet::*;
+
+ #[test]
+ fn test_highlight_code_segment() {
+ assert!(run("make", "").is_empty());
+ assert_eq!(
+ &run("make", "make all CC=clang -q"),
+ &[CommandName("make"), NormalCode(" all CC=clang -q")]
+ );
+ assert_eq!(
+ &run("make", " make money --always-make"),
+ &[
+ NormalCode(" "),
+ CommandName("make"),
+ NormalCode(" money --always-make")
+ ]
+ );
+ assert_eq!(
+ &run("git commit", "git commit -m 'git commit'"),
+ &[CommandName("git commit"), NormalCode(" -m 'git commit'"),]
+ );
+ }
+
+ #[test]
+ fn test_i18n() {
+ assert_eq!(
+ &run("mäke", "mäke höhlenrätselbücher"),
+ &[CommandName("mäke"), NormalCode(" höhlenrätselbücher")]
+ );
+ assert_eq!(
+ &run(
+ "Müll",
+ "1000 Gründe warum Müll heute größer ist als Müll früher, ärgerlich"
+ ),
+ &[
+ NormalCode("1000 Gründe warum "),
+ CommandName("Müll"),
+ NormalCode(" heute größer ist als "),
+ CommandName("Müll"),
+ NormalCode(" früher, ärgerlich")
+ ]
+ );
+ assert_eq!(
+ &run(
+ "übergang",
+ "die Zustandsübergangsfunktion übergang Änderungen",
+ ),
+ &[
+ NormalCode("die Zustandsübergangsfunktion "),
+ CommandName("übergang"),
+ NormalCode(" Änderungen")
+ ],
+ );
+ }
+
+ #[test]
+ fn test_empty_command() {
+ let segment = "some code";
+ let snippets = [NormalCode(segment)];
+
+ assert_eq!(run("", segment), snippets);
+ assert_eq!(run(" ", segment), snippets);
+ assert_eq!(run(" \t ", segment), snippets);
+ }
}
- #[test]
- fn test_i18n() {
- assert_eq!(
- &run("mäke", "mäke höhlenrätselbücher"),
- &[CommandName("mäke"), NormalCode(" höhlenrätselbücher")]
- );
- assert_eq!(
- &run(
- "Müll",
- "1000 Gründe warum Müll heute größer ist als Müll früher, ärgerlich"
- ),
- &[
- NormalCode("1000 Gründe warum "),
- CommandName("Müll"),
- NormalCode(" heute größer ist als "),
- CommandName("Müll"),
- NormalCode(" früher, ärgerlich")
- ]
- );
- assert_eq!(
- &run(
- "übergang",
- "die Zustandsübergangsfunktion übergang Änderungen",
- ),
- &[
- NormalCode("die Zustandsübergangsfunktion "),
- CommandName("übergang"),
- NormalCode(" Änderungen")
- ],
- );
+ mod placeholders {
+ use super::*;
+ use PageSnippet::*;
+
+ #[test]
+ fn placeholder_vs_escaped() {
+ assert_eq!(
+ run("ping", "ping {{example.com}}"),
+ [
+ CommandName("ping"),
+ NormalCode(" "),
+ Placeholder("example.com"),
+ ],
+ );
+ assert_eq!(
+ run(
+ "docker inspect",
+ r"docker inspect --format '\{\{range.NetworkSettings.Networks\}\}\{\{.IPAddress\}\}\{\{end\}\}' {{container}}"
+ ),
+ [
+ CommandName("docker inspect"),
+ NormalCode(
+ " --format '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "
+ ),
+ Placeholder("container"),
+ ],
+ );
+ assert_eq!(
+ run("mount", r"mount \\{{computer_name}}\{{share_name}} Z:"),
+ [
+ CommandName("mount"),
+ NormalCode(r" \\"),
+ Placeholder("computer_name"),
+ NormalCode(r"\"),
+ Placeholder("share_name"),
+ NormalCode(" Z:"),
+ ],
+ );
+
+ assert_eq!(run("", r"\{"), [NormalCode(r"\{")]);
+ assert_eq!(run("", r"\{{a"), [NormalCode(r"\{{a")]);
+ assert_eq!(run("", r"\{{a}}"), [NormalCode(r"\"), Placeholder("a")]);
+
+ // Placeholder has begin marker, but no end marker
+ assert_eq!(run("", r"{{\}\}}"), [NormalCode("{{}}}")]);
+ }
+
+ #[test]
+ fn outer_precedence() {
+ assert_eq!(
+ run("git stash", "git stash show --patch {{stash@{0}}}"),
+ [
+ CommandName("git stash"),
+ NormalCode(" show --patch "),
+ Placeholder("stash@{0}"),
+ ],
+ );
+
+ // The following is not listed in the specification, but this is the highlighting I would expect.
+ assert_eq!(
+ run("rg", "rg {{}}}"),
+ [CommandName("rg"), NormalCode(" "), Placeholder("}")]
+ );
+
+ // And these are just to document the current behavior
+ assert_eq!(run("", "{{{}}}"), [Placeholder("{}")]);
+ assert_eq!(run("", "{{{{}}}"), [Placeholder("{{}")]);
+ assert_eq!(run("", "{{{}}}}"), [Placeholder("{}}")]);
+ }
+
+ #[test]
+ fn escaped_inside_placeholder() {
+ assert_eq!(
+ run(
+ "playerctl",
+ r#"playerctl metadata {{[-f|--format]}} "{{Now playing: \{\{artist\}\} - \{\{album\}\} - \{\{title\}\}}}""#
+ ),
+ [
+ CommandName("playerctl"),
+ NormalCode(" metadata "),
+ PlaceholderVariants {
+ short: "-f",
+ long: "--format"
+ },
+ NormalCode(" \""),
+ Placeholder("Now playing: {{artist}} - {{album}} - {{title}}"),
+ NormalCode("\""),
+ ],
+ );
+ }
+
+ #[test]
+ fn placeholder_inside_escaped() {
+ assert_eq!(
+ run("test", r"test \{\{{{var}} normal\}\}"),
+ [
+ CommandName("test"),
+ NormalCode(" {{"),
+ Placeholder("var"),
+ NormalCode(" normal}}"),
+ ],
+ );
+ }
+
+ #[test]
+ /// Regression test for
+ fn prefix_check_character_boundary() {
+ assert_eq!("Ä".len(), 2);
+ assert_eq!(run("", r"Äxx{{x}}"), [NormalCode("Äxx"), Placeholder("x")],);
+ }
}
- #[test]
- fn test_empty_command() {
- let segment = "some code";
- let snippets = [NormalCode(segment)];
+ mod placeholder_variants {
+ use super::*;
+ use PageSnippet::*;
- assert_eq!(run("", segment), snippets);
- assert_eq!(run(" ", segment), snippets);
- assert_eq!(run(" \t ", segment), snippets);
+ #[test]
+ fn missing_marker() {
+ assert_eq!(
+ run("foo", "{{[short|long]}}"),
+ [PlaceholderVariants {
+ short: "short",
+ long: "long"
+ }]
+ );
+
+ assert_eq!(run("foo", "{{short|long]}}"), [Placeholder("short|long]")]);
+ assert_eq!(run("foo", "{{[short|long}}"), [Placeholder("[short|long")]);
+ assert_eq!(run("foo", "{{[shortlong]}}"), [Placeholder("[shortlong]")]);
+ }
+
+ /// The character `[` is a valid command name
+ #[test]
+ fn command_name_interaction() {
+ for name in ["[", "]", "|"] {
+ assert_eq!(
+ run(name, "{{[short|long]}}"),
+ [PlaceholderVariants {
+ short: "short",
+ long: "long"
+ }]
+ );
+ }
+ }
+
+ #[test]
+ fn empty_variant() {
+ for name in ["[", "]", "|"] {
+ assert_eq!(
+ run(name, "{{[|long]}}"),
+ [PlaceholderVariants {
+ short: "",
+ long: "long"
+ }]
+ );
+ assert_eq!(
+ run(name, "{{[short|]}}"),
+ [PlaceholderVariants {
+ short: "short",
+ long: ""
+ }]
+ );
+ assert_eq!(run(name, "{{[|]}}"), [] as [PageSnippet::; 0]);
+ }
+ }
}
}
diff --git a/src/line_iterator.rs b/src/line_iterator.rs
index 2e11378..98088c0 100644
--- a/src/line_iterator.rs
+++ b/src/line_iterator.rs
@@ -53,7 +53,7 @@ impl Iterator for LineIterator {
match bytes_read {
Ok(0) => None,
Err(e) => {
- warn!("Could not read line from reader: {:?}", e);
+ warn!("Could not read line from reader: {e:?}");
None
}
Ok(_) => {
@@ -68,7 +68,7 @@ impl Iterator for LineIterator {
.find(|b| matches!(b, Ok(b'\n') | Err(_)))
.transpose()
{
- warn!("Could not read line from reader: {:?}", e);
+ warn!("Could not read line from reader: {e:?}");
return None;
}
self.first_line = false;
diff --git a/src/main.rs b/src/main.rs
index cfd00db..ca9faf3 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -15,6 +15,8 @@
#![allow(clippy::similar_names)]
#![allow(clippy::struct_excessive_bools)]
#![allow(clippy::too_many_lines)]
+#![allow(clippy::unnecessary_debug_formatting)]
+#![allow(clippy::while_let_loop)]
#[cfg(not(any(
feature = "native-tls",
@@ -33,9 +35,12 @@ use std::{
process::{Command, ExitCode},
};
-use anyhow::{anyhow, Context, Result};
-use app_dirs::AppInfo;
+use anyhow::{Context, Result, anyhow};
+use cache::CacheConfig;
use clap::Parser;
+use config::{ConfigLoader, Language, StyleConfig, TlsBackend};
+use log::debug;
+use types::PlatformType;
mod cache;
mod cli;
@@ -48,115 +53,68 @@ mod types;
mod utils;
use crate::{
- cache::{Cache, CacheFreshness, PageLookupResult, TLDR_PAGES_DIR},
+ cache::{Cache, PageLookupResult, TLDR_PAGES_DIR},
cli::Cli,
- config::{get_config_dir, get_config_path, make_default_config, Config, PathWithSource},
- extensions::Dedup,
+ config::{
+ Config, PathWithSource, PlaceholderFormat, get_config_dir, make_default_config,
+ supported_tls_backends_string,
+ },
output::print_page,
- types::{ColorOptions, PlatformType},
+ types::ColorOptions,
utils::{print_error, print_warning},
};
const NAME: &str = "tealdeer";
-const APP_INFO: AppInfo = AppInfo {
- name: NAME,
- author: NAME,
-};
-
-/// The cache should be updated if it was explicitly requested,
-/// or if an automatic update is due and allowed.
-fn should_update_cache(cache: &Cache, args: &Cli, config: &Config) -> bool {
- args.update
- || (!args.no_auto_update
- && config.updates.auto_update
- && cache
- .last_update()
- .map_or(true, |ago| ago >= config.updates.auto_update_interval))
-}
-
-#[derive(PartialEq)]
-enum CheckCacheResult {
- CacheFound,
- CacheMissing,
-}
-
-/// Check the cache for freshness. If it's stale or missing, show a warning.
-fn check_cache(cache: &Cache, args: &Cli, enable_styles: bool) -> CheckCacheResult {
- match cache.freshness() {
- CacheFreshness::Fresh => CheckCacheResult::CacheFound,
- CacheFreshness::Stale(_) if args.quiet => CheckCacheResult::CacheFound,
- CacheFreshness::Stale(age) => {
- print_warning(
- enable_styles,
- &format!(
- "The cache hasn't been updated for {} days.\n\
- You should probably run `tldr --update` soon.",
- age.as_secs() / 24 / 3600
- ),
- );
- CheckCacheResult::CacheFound
- }
- CacheFreshness::Missing => {
- print_error(
- enable_styles,
- &anyhow::anyhow!(
- "Page cache not found. Please run `tldr --update` to download the cache."
- ),
- );
- println!("\nNote: You can optionally enable automatic cache updates by adding the");
- println!("following config to your config file:\n");
- println!(" [updates]");
- println!(" auto_update = true\n");
- println!("The path to your config file can be looked up with `tldr --show-paths`.");
- println!("To create an initial config file, use `tldr --seed-config`.\n");
- println!("You can find more tips and tricks in our docs:\n");
- println!(" https://tealdeer-rs.github.io/tealdeer/config_updates.html");
- CheckCacheResult::CacheMissing
- }
- }
-}
+static TEALDEER_PAGE: &str =
+ include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/pages/tealdeer.md"));
/// Clear the cache
-fn clear_cache(cache: &Cache, quietly: bool) -> Result<()> {
- let cache_dir_found = cache.clear().context("Could not clear cache")?;
+fn clear_cache(cache: Cache, quietly: bool) -> Result<()> {
+ let cache_dir = cache.config().pages_directory.display();
+ cache.clear().context("Could not clear cache")?;
if !quietly {
- let cache_dir = cache.cache_dir().display();
- if cache_dir_found {
- eprintln!("Successfully cleared cache at `{cache_dir}`.");
- } else {
- eprintln!("Cache directory not found at `{cache_dir}`, nothing to do.");
- }
+ eprintln!("Successfully cleared cache at `{cache_dir}`.");
}
Ok(())
}
/// Update the cache
-fn update_cache(cache: &Cache, archive_source: &str, quietly: bool) -> Result<()> {
- cache
- .update(archive_source)
+fn update_cache(
+ cache: &mut Cache,
+ archive_source: &str,
+ tls_backend: TlsBackend,
+ quietly: bool,
+) -> Result<()> {
+ let downloaded_languages = cache
+ .update(archive_source, tls_backend)
.context("Could not update cache")?;
if !quietly {
eprintln!("Successfully updated cache.");
+ eprint!("Pages for the following languages were downloaded: ");
+ let language_strings: Vec<_> = downloaded_languages
+ .into_iter()
+ .map(|lang| lang.0)
+ .collect();
+ if language_strings.is_empty() {
+ eprintln!("(none)");
+ } else {
+ eprintln!("{}", language_strings.join(", "));
+ }
}
Ok(())
}
/// Show file paths
fn show_paths(config: &Config) {
- let config_dir = get_config_dir().map_or_else(
- |e| format!("[Error: {e}]"),
- |(mut path, source)| {
- path.push(""); // Trailing path separator
- match path.to_str() {
- Some(path) => format!("{path} ({source})"),
- None => "[Invalid]".to_string(),
- }
- },
- );
- let config_path = get_config_path().map_or_else(
- |e| format!("[Error: {e}]"),
- |(path, _)| path.display().to_string(),
- );
+ let config_dir = {
+ let (mut path, source) = get_config_dir();
+ path.push(""); // Trailing path separator
+ match path.to_str() {
+ Some(path) => format!("{path} ({source})"),
+ None => "[Invalid]".to_string(),
+ }
+ };
+ let config_path = config.file_path.to_string();
let cache_dir = config.directories.cache_dir.to_string();
let pages_dir = {
let mut path = config.directories.cache_dir.path.clone();
@@ -175,8 +133,8 @@ fn show_paths(config: &Config) {
println!("Custom pages dir: {custom_pages_dir}");
}
-fn create_config() -> Result<()> {
- let config_file_path = make_default_config().context("Could not create seed config")?;
+fn create_config(path: Option<&Path>) -> Result<()> {
+ let config_file_path = make_default_config(path).context("Could not create seed config")?;
eprintln!(
"Successfully created seed config file here: {}",
config_file_path.to_str().unwrap()
@@ -192,42 +150,6 @@ fn init_log() {
#[cfg(not(feature = "logging"))]
fn init_log() {}
-fn get_languages(env_lang: Option<&str>, env_language: Option<&str>) -> Vec {
- // Language list according to
- // https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md#language
-
- if env_lang.is_none() {
- return vec!["en".to_string()];
- }
- let env_lang = env_lang.unwrap();
-
- // Create an iterator that contains $LANGUAGE (':' separated list) followed by $LANG (single language)
- let locales = env_language.unwrap_or("").split(':').chain([env_lang]);
-
- let mut lang_list = Vec::new();
- for locale in locales {
- // Language plus country code (e.g. `en_US`)
- if locale.len() >= 5 && locale.chars().nth(2) == Some('_') {
- lang_list.push(&locale[..5]);
- }
- // Language code only (e.g. `en`)
- if locale.len() >= 2 && locale != "POSIX" {
- lang_list.push(&locale[..2]);
- }
- }
-
- lang_list.push("en");
- lang_list.clear_duplicates();
- lang_list.into_iter().map(str::to_string).collect()
-}
-
-fn get_languages_from_env() -> Vec {
- get_languages(
- std::env::var("LANG").ok().as_deref(),
- std::env::var("LANGUAGE").ok().as_deref(),
- )
-}
-
fn spawn_editor(custom_pages_dir: &Path, file_name: &str) -> Result<()> {
create_dir_all(custom_pages_dir).context("Failed to create custom pages directory")?;
@@ -279,7 +201,26 @@ fn main() -> ExitCode {
fn try_main(args: Cli, enable_styles: bool) -> Result {
// Look up config file, if none is found fall back to default config.
- let config = Config::load(enable_styles).context("Could not load config")?;
+ debug!("Loading config");
+ let config_loader = match &args.config_path {
+ Some(path) if !args.seed_config => ConfigLoader::read(path.clone(), &args.override_config)
+ .context("Could not read config from given path")?,
+ _ => ConfigLoader::read_default_path(&args.override_config)
+ .context("Could not read config from default path")?,
+ };
+ let mut config = config_loader.load()?;
+
+ // Override styles if needed
+ if !enable_styles {
+ config.style = StyleConfig::default();
+ }
+
+ config.display.placeholder_format = match (args.short_options, args.long_options) {
+ (false, false) => config.display.placeholder_format, // keep old value
+ (true, false) => PlaceholderFormat::Short,
+ (false, true) => PlaceholderFormat::Long,
+ (true, true) => PlaceholderFormat::Both,
+ };
let custom_pages_dir = config
.directories
@@ -313,148 +254,191 @@ fn try_main(args: Cli, enable_styles: bool) -> Result {
// Create a basic config and exit
if args.seed_config {
- create_config()?;
+ create_config(args.config_path.as_deref())?;
return Ok(ExitCode::SUCCESS);
}
- let platforms = compute_platforms(args.platforms.as_ref());
-
// If a local file was passed in, render it and exit
if let Some(file) = args.render {
- let path = PageLookupResult::with_page(file);
- print_page(&path, args.raw, enable_styles, args.pager, &config)?;
+ let reader = PageLookupResult::with_page(file).reader()?;
+ print_page(reader, args.raw, enable_styles, args.pager, &config)?;
return Ok(ExitCode::SUCCESS);
}
- // Instantiate cache. This will not yet create the cache directory!
- let cache = Cache::new(
- &config.directories.cache_dir.path,
- enable_styles,
- config.updates.tls_backend,
- );
-
- // Clear cache, pass through
- if args.clear_cache {
- clear_cache(&cache, args.quiet)?;
+ // The tealdeer page is embedded in the binary, no cache needed
+ if command == "tealdeer" {
+ print_page(
+ TEALDEER_PAGE.as_bytes(),
+ args.raw,
+ enable_styles,
+ args.pager,
+ &config,
+ )?;
+ return Ok(ExitCode::SUCCESS);
}
- if should_update_cache(&cache, &args, &config) {
- update_cache(&cache, &config.updates.archive_source, args.quiet)?;
- } else if (args.list || !args.command.is_empty())
- && check_cache(&cache, &args, enable_styles) == CheckCacheResult::CacheMissing
- {
- // Cache is needed, but missing
- return Ok(ExitCode::FAILURE);
+ if let Some(platforms) = args.platforms {
+ config.search.platforms = platforms;
+ if !config.search.platforms.contains(&PlatformType::Common) {
+ config.search.platforms.push(PlatformType::Common);
+ }
+ }
+
+ let (search_languages, download_languages): (&[_], &[_]) = match args.language.as_deref() {
+ Some(lang) => (&[Language(lang)], &[Language(lang)]),
+ None => (&config.search.languages, &config.updates.download_languages),
+ };
+
+ let cache_config = CacheConfig {
+ pages_directory: &config.directories.cache_dir.path().join(TLDR_PAGES_DIR),
+ custom_pages_directory: config
+ .directories
+ .custom_pages_dir
+ .as_ref()
+ .map(PathWithSource::path),
+ platforms: &config.search.platforms,
+ search_languages,
+ download_languages,
+ };
+
+ if args.clear_cache {
+ if let Some(cache) = Cache::open(cache_config)? {
+ clear_cache(cache, args.quiet)?;
+ }
+ return Ok(ExitCode::SUCCESS);
+ }
+
+ let cache = if args.update || config.updates.auto_update && !args.no_auto_update {
+ let (mut cache, was_created) = Cache::open_or_create(cache_config)?;
+ if was_created || args.update || cache.age()? >= config.updates.auto_update_interval {
+ let result = update_cache(
+ &mut cache,
+ config.updates.archive_source,
+ config.updates.tls_backend,
+ args.quiet,
+ );
+
+ if let Err(e) = result {
+ print_error(enable_styles, &e);
+
+ eprintln!();
+ eprintln!(
+ "Note: Update errors are often caused by unexpected or missing TLS certificates."
+ );
+ eprintln!(
+ "You are currently using the following TLS backend: {}",
+ config.updates.tls_backend,
+ );
+ eprintln!(
+ "Try changing the updates.tls_backend setting in the config file, for example:"
+ );
+ eprintln!();
+ eprintln!(" [updates]");
+ eprintln!(" tls_backend = \"rustls-with-native-roots\"");
+ eprintln!();
+ eprintln!(
+ "This build of tealdeer has support for the following options: {}",
+ supported_tls_backends_string(),
+ );
+
+ return Ok(ExitCode::FAILURE);
+ }
+ }
+
+ cache
+ } else if args.list || !command.is_empty() {
+ // Cache is needed for these commands to work
+ let Some(cache) = Cache::open(cache_config)? else {
+ if !args.quiet {
+ print_error(
+ enable_styles,
+ &anyhow::anyhow!(
+ "Page cache not found. Please run `tldr --update` to download the cache."
+ ),
+ );
+ println!("\nNote: You can optionally enable automatic cache updates by adding the");
+ println!("following config to your config file:\n");
+ println!(" [updates]");
+ println!(" auto_update = true\n");
+ println!("The path to your config file can be looked up with `tldr --show-paths`.");
+ println!("To create an initial config file, use `tldr --seed-config`.\n");
+ println!("You can find more tips and tricks in our docs:\n");
+ println!(" https://docs.tealdeer.org");
+ }
+
+ return Ok(ExitCode::FAILURE);
+ };
+
+ if let Some(max_cache_age) = config.updates.warn_cache_age {
+ let age = cache.age()?;
+ if age > max_cache_age && !args.quiet {
+ print_warning(
+ enable_styles,
+ &format!(
+ "The cache hasn't been updated for {} days.\n\
+ You should probably run `tldr --update` soon.",
+ age.as_secs() / 24 / 3600
+ ),
+ );
+ }
+ }
+
+ cache
+ } else {
+ // There is nothing left to do
+ return Ok(ExitCode::SUCCESS);
};
- // List cached commands and exit
if args.list {
- println!(
- "{}",
- cache.list_pages(custom_pages_dir, &platforms).join("\n")
- );
+ for page in cache.list_pages()? {
+ println!("{page}");
+ }
return Ok(ExitCode::SUCCESS);
}
// Show command from cache
if !command.is_empty() {
- // Collect languages
- let languages = args
- .language
- .map_or_else(get_languages_from_env, |lang| vec![lang]);
+ // TODO: Remove this check 1 year after version 1.7.0 was released
+ if cache.old_custom_pages_exist()? {
+ print_warning(
+ enable_styles,
+ &format!(
+ "Custom pages using the old naming convention were found in {}.\n\
+ Please rename them to follow the new convention:\n\
+ - `.page` → `.page.md`\n\
+ - `.patch` → `.patch.md`",
+ cache
+ .config()
+ .custom_pages_directory
+ .expect("Old custom pages can only exist in custom pages directory")
+ .display(),
+ ),
+ );
+ }
- // Search for command in cache
- let Some(lookup_result) = cache.find_page(
- &command,
- &languages,
- config
- .directories
- .custom_pages_dir
- .as_ref()
- .map(PathWithSource::path),
- &platforms,
- ) else {
+ let Some(result) = cache.find_page(&command) else {
if !args.quiet {
print_warning(
enable_styles,
&format!(
- "Page `{}` not found in cache.\n\
+ "Page `{command}` not found in cache.\n\
Try updating with `tldr --update`, or submit a pull request to:\n\
- https://github.com/tldr-pages/tldr",
- &command
+ https://github.com/tldr-pages/tldr"
),
);
}
-
return Ok(ExitCode::FAILURE);
};
- print_page(&lookup_result, args.raw, enable_styles, args.pager, &config)?;
+ print_page(
+ result.reader()?,
+ args.raw,
+ enable_styles,
+ args.pager,
+ &config,
+ )?;
}
Ok(ExitCode::SUCCESS)
}
-
-/// Returns the passed or default platform types and appends `PlatformType::Common` as fallback.
-fn compute_platforms(platforms: Option<&Vec>) -> Vec {
- match platforms {
- Some(p) => {
- let mut result = p.clone();
- if !result.contains(&PlatformType::Common) {
- result.push(PlatformType::Common);
- }
- result
- }
- None => vec![PlatformType::current(), PlatformType::Common],
- }
-}
-
-#[cfg(test)]
-mod test {
- use crate::get_languages;
-
- mod language {
- use super::*;
-
- #[test]
- fn missing_lang_env() {
- let lang_list = get_languages(None, Some("de:fr"));
- assert_eq!(lang_list, ["en"]);
- let lang_list = get_languages(None, None);
- assert_eq!(lang_list, ["en"]);
- }
-
- #[test]
- fn missing_language_env() {
- let lang_list = get_languages(Some("de"), None);
- assert_eq!(lang_list, ["de", "en"]);
- }
-
- #[test]
- fn preference_order() {
- let lang_list = get_languages(Some("de"), Some("fr:cn"));
- assert_eq!(lang_list, ["fr", "cn", "de", "en"]);
- }
-
- #[test]
- fn country_code_expansion() {
- let lang_list = get_languages(Some("pt_BR"), None);
- assert_eq!(lang_list, ["pt_BR", "pt", "en"]);
- }
-
- #[test]
- fn ignore_posix_and_c() {
- let lang_list = get_languages(Some("POSIX"), None);
- assert_eq!(lang_list, ["en"]);
- let lang_list = get_languages(Some("C"), None);
- assert_eq!(lang_list, ["en"]);
- }
-
- #[test]
- fn no_duplicates() {
- let lang_list = get_languages(Some("de"), Some("fr:de:cn:de"));
- assert_eq!(lang_list, ["fr", "de", "cn", "en"]);
- }
- }
-}
diff --git a/src/output.rs b/src/output.rs
index abef1db..41c1119 100644
--- a/src/output.rs
+++ b/src/output.rs
@@ -1,14 +1,13 @@
//! Functions for printing pages to the terminal
-use std::io::{self, BufRead, Write};
+use std::io::{self, BufRead, BufReader, Read, Write};
use anyhow::{Context, Result};
use yansi::Paint;
use crate::{
- cache::PageLookupResult,
- config::{Config, StyleConfig},
- formatter::{highlight_lines, PageSnippet},
+ config::{Config, PlaceholderFormat, StyleConfig},
+ formatter::{PageSnippet, highlight_lines},
line_iterator::LineIterator,
};
@@ -30,14 +29,13 @@ fn configure_pager(enable_styles: bool) {
/// Print page by path
pub fn print_page(
- lookup_result: &PageLookupResult,
+ reader: impl Read,
enable_markdown: bool,
enable_styles: bool,
use_pager: bool,
config: &Config,
) -> Result<()> {
- // Create reader from file(s)
- let reader = lookup_result.reader()?;
+ let reader = BufReader::new(reader);
// Configure pager if applicable
if use_pager || config.display.use_pager {
@@ -56,11 +54,17 @@ pub fn print_page(
}
} else {
// Closure that processes a page snippet and writes it to stdout
- let mut process_snippet = |snip: PageSnippet<'_>| {
+ let mut process_snippet = |snip: PageSnippet<&str>| {
if snip.is_empty() {
Ok(())
} else {
- print_snippet(&mut handle, snip, &config.style).context("Failed to print snippet")
+ print_snippet(
+ &mut handle,
+ snip,
+ &config.style,
+ config.display.placeholder_format,
+ )
+ .context("Failed to print snippet")
}
};
@@ -69,9 +73,11 @@ pub fn print_page(
LineIterator::new(reader),
&mut process_snippet,
!config.display.compact,
+ config.display.show_title,
+ config.display.indent,
)
.context("Could not write to stdout")?;
- };
+ }
// We're done outputting data, flush stdout now!
handle.flush().context("Could not flush stdout")?;
@@ -81,17 +87,30 @@ pub fn print_page(
fn print_snippet(
writer: &mut impl Write,
- snip: PageSnippet<'_>,
+ snip: PageSnippet<&str>,
style: &StyleConfig,
+ placeholder_format: PlaceholderFormat,
) -> io::Result<()> {
use PageSnippet::*;
match snip {
- CommandName(s) => write!(writer, "{}", s.paint(style.command_name)),
- Variable(s) => write!(writer, "{}", s.paint(style.example_variable)),
+ CommandName(s) | Title(s) => write!(writer, "{}", s.paint(style.command_name)),
+ Placeholder(s) => write!(writer, "{}", s.paint(style.example_variable)),
+ PlaceholderVariants { short, long } => match placeholder_format {
+ PlaceholderFormat::Short => write!(writer, "{}", short.paint(style.example_code)),
+ PlaceholderFormat::Long => write!(writer, "{}", long.paint(style.example_code)),
+ PlaceholderFormat::Both => {
+ write!(
+ writer,
+ "{}",
+ format!("[{short}|{long}]").paint(style.example_code)
+ )
+ }
+ },
NormalCode(s) => write!(writer, "{}", s.paint(style.example_code)),
- Description(s) => writeln!(writer, " {}", s.paint(style.description)),
- Text(s) => writeln!(writer, " {}", s.paint(style.example_text)),
+ Description(s) => write!(writer, "{}", s.paint(style.description)),
+ Text(s) => write!(writer, "{}", s.paint(style.example_text)),
+ Indent(n) => write!(writer, "{:n$}", ' '),
Linebreak => writeln!(writer),
}
}
diff --git a/src/types.rs b/src/types.rs
index 416d267..7ca6e2d 100644
--- a/src/types.rs
+++ b/src/types.rs
@@ -118,18 +118,14 @@ impl PlatformType {
#[derive(Debug, Eq, PartialEq, Copy, Clone, Deserialize, clap::ValueEnum)]
#[serde(rename_all = "lowercase")]
+#[derive(Default)]
pub enum ColorOptions {
Always,
+ #[default]
Auto,
Never,
}
-impl Default for ColorOptions {
- fn default() -> Self {
- Self::Auto
- }
-}
-
#[derive(Debug, Eq, PartialEq)]
pub enum LineType {
Empty,
@@ -205,6 +201,8 @@ pub enum PathSource {
EnvVar,
/// Config file
ConfigFile,
+ /// CLI argument override
+ Cli,
}
impl fmt::Display for PathSource {
@@ -216,6 +214,7 @@ impl fmt::Display for PathSource {
Self::OsConvention => "OS convention",
Self::EnvVar => "env variable",
Self::ConfigFile => "config file",
+ Self::Cli => "command line argument",
}
)
}
diff --git a/tests/cache/pages/common/git-checkout.md b/tests/cache/pages.en/common/git-checkout.md
similarity index 100%
rename from tests/cache/pages/common/git-checkout.md
rename to tests/cache/pages.en/common/git-checkout.md
diff --git a/tests/cache/pages/common/inkscape-v1.md b/tests/cache/pages.en/common/inkscape-v1.md
similarity index 100%
rename from tests/cache/pages/common/inkscape-v1.md
rename to tests/cache/pages.en/common/inkscape-v1.md
diff --git a/tests/cache/pages/common/inkscape-v2.md b/tests/cache/pages.en/common/inkscape-v2.md
similarity index 100%
rename from tests/cache/pages/common/inkscape-v2.md
rename to tests/cache/pages.en/common/inkscape-v2.md
diff --git a/tests/cache/pages.en/common/playerctl.md b/tests/cache/pages.en/common/playerctl.md
new file mode 100644
index 0000000..8b54f12
--- /dev/null
+++ b/tests/cache/pages.en/common/playerctl.md
@@ -0,0 +1,32 @@
+# playerctl
+
+> Control media players via MPRIS.
+> More information: .
+
+- Toggle play:
+
+`playerctl play-pause`
+
+- Skip to the next track:
+
+`playerctl next`
+
+- Go back to the previous track:
+
+`playerctl previous`
+
+- List all players:
+
+`playerctl {{[-l|--list-all]}}`
+
+- Send a command to a specific player:
+
+`playerctl {{[-p|--player]}} {{player_name}} {{play-pause|next|previous|...}}`
+
+- Send a command to all players:
+
+`playerctl {{[-a|--all-players]}} {{play-pause|next|previous|...}}`
+
+- Display metadata about the current track:
+
+`playerctl metadata {{[-f|--format]}} "{{Now playing: \{\{artist\}\} - \{\{album\}\} - \{\{title\}\}}}"`
diff --git a/tests/cache/pages/common/which.md b/tests/cache/pages.en/common/which.md
similarity index 100%
rename from tests/cache/pages/common/which.md
rename to tests/cache/pages.en/common/which.md
diff --git a/tests/lib.rs b/tests/lib.rs
index 420eb08..53c15ef 100644
--- a/tests/lib.rs
+++ b/tests/lib.rs
@@ -1,7 +1,7 @@
//! Integration tests.
use std::{
- fs::{self, create_dir_all, File},
+ fs::{self, File, create_dir_all},
io::{self, Write},
path::{Path, PathBuf},
process::Command,
@@ -11,6 +11,7 @@ use std::{
use assert_cmd::prelude::*;
use predicates::{
boolean::PredicateBooleanExt,
+ ord::eq,
prelude::predicate::str::{contains, diff, is_empty, is_match},
};
use tempfile::{Builder as TempfileBuilder, TempDir};
@@ -36,14 +37,11 @@ impl TestEnv {
features: vec![],
};
- create_dir_all(&this.cache_dir()).unwrap();
- create_dir_all(&this.config_dir()).unwrap();
- create_dir_all(&this.custom_pages_dir()).unwrap();
+ create_dir_all(this.cache_dir()).unwrap();
+ create_dir_all(this.config_dir()).unwrap();
+ create_dir_all(this.custom_pages_dir()).unwrap();
- this.append_to_config(format!(
- "directories.cache_dir = '{}'\n",
- this.cache_dir().to_str().unwrap(),
- ));
+ this.init_config();
this
}
@@ -69,6 +67,33 @@ impl TestEnv {
.write_all(content.as_ref().as_bytes())
.expect("Failed to append to config file.");
}
+ fn delete_config(&self) {
+ fs::remove_file(self.config_dir().join("config.toml")).unwrap();
+ }
+ fn init_config(&self) {
+ self.append_to_config(format!(
+ "directories.cache_dir = '{}'\n",
+ self.cache_dir().to_str().unwrap(),
+ ));
+ }
+
+ fn create_secondary_config(self) -> Self {
+ self.append_to_secondary_config(format!(
+ "directories.cache_dir = '{}'\n",
+ self.cache_dir().to_str().unwrap(),
+ ));
+ self
+ }
+
+ fn append_to_secondary_config(&self, content: impl AsRef) {
+ File::options()
+ .create(true)
+ .append(true)
+ .open(self.config_dir().join("config-secondary.toml"))
+ .expect("Failed to open config file")
+ .write_all(content.as_ref().as_bytes())
+ .expect("Failed to append to config file.");
+ }
fn remove_initial_config(self) -> Self {
let _ = fs::remove_file(self.config_dir().join("config.toml"));
@@ -82,7 +107,21 @@ impl TestEnv {
/// Add entry for that environment to an OS-specific subfolder.
fn add_os_entry(&self, os: &str, name: &str, contents: &str) {
- let dir = self.cache_dir().join(TLDR_PAGES_DIR).join("pages").join(os);
+ self.add_os_lang_entry(os, "en", name, contents);
+ }
+
+ /// Add entry for that environment to a language-specific subfolder.
+ fn add_lang_entry(&self, lang: &str, name: &str, contents: &str) {
+ self.add_os_lang_entry("common", lang, name, contents);
+ }
+
+ /// Add entry for that environment to an OS- and language specific subfolder.
+ fn add_os_lang_entry(&self, os: &str, lang: &str, name: &str, contents: &str) {
+ let dir = self
+ .cache_dir()
+ .join(TLDR_PAGES_DIR)
+ .join(format!("pages.{lang}"))
+ .join(os);
create_dir_all(&dir).unwrap();
fs::write(dir.join(format!("{name}.md")), contents.as_bytes()).unwrap();
@@ -129,6 +168,19 @@ impl TestEnv {
}
let run = build.run().expect("Failed to build tealdeer for testing");
let mut cmd = run.command();
+
+ // Avoid inheriting those from the test process. We can't just use .env_clear() because
+ // this breaks tests on Windows in GitHub Actions.
+ let relevant_env_variables = [
+ "LANG",
+ "LANGUAGE",
+ "TEALDEER_CACHE_DIR",
+ "EDITOR",
+ "NO_COLOR",
+ ];
+ for variable_name in relevant_env_variables {
+ cmd.env_remove(variable_name);
+ }
cmd.env("TEALDEER_CONFIG_DIR", self.config_dir().to_str().unwrap());
cmd
}
@@ -183,6 +235,61 @@ fn test_cannot_build_without_tls_feature() {
let _ = TestEnv::new().no_default_features().command();
}
+#[test]
+fn test_load_the_correct_config() {
+ let testenv = TestEnv::new()
+ .install_default_cache()
+ .create_secondary_config();
+ testenv.append_to_secondary_config(include_str!("style-config.toml"));
+
+ let expected_default = include_str!("rendered/inkscape-default.expected");
+ let expected_with_config = include_str!("rendered/inkscape-with-config.expected");
+
+ testenv
+ .command()
+ .args(["--color", "always", "inkscape-v2"])
+ .assert()
+ .success()
+ .stdout(diff(expected_default));
+
+ testenv
+ .command()
+ .args([
+ "--color",
+ "always",
+ "--config-path",
+ testenv
+ .config_dir()
+ .join("config-secondary.toml")
+ .to_str()
+ .unwrap(),
+ "inkscape-v2",
+ ])
+ .assert()
+ .success()
+ .stdout(diff(expected_with_config));
+}
+
+#[test]
+fn test_fail_on_custom_config_path_is_directory() {
+ let testenv = TestEnv::new();
+ let error = if cfg!(windows) {
+ "Access is denied"
+ } else {
+ "Is a directory"
+ };
+ testenv
+ .command()
+ .args([
+ "--config-path",
+ testenv.config_dir().to_str().unwrap(),
+ "sl",
+ ])
+ .assert()
+ .failure()
+ .stderr(contains(error));
+}
+
#[test]
fn test_missing_cache() {
TestEnv::new()
@@ -193,6 +300,16 @@ fn test_missing_cache() {
.stderr(contains("Page cache not found. Please run `tldr --update`"));
}
+#[test]
+fn test_tealdeer_page_works_without_cache() {
+ TestEnv::new()
+ .command()
+ .args(["tealdeer"])
+ .assert()
+ .success()
+ .stdout(contains("for your installed tealdeer version"));
+}
+
#[cfg_attr(feature = "ignore-online-tests", ignore = "online test")]
#[test]
fn test_update_cache_default_features() {
@@ -282,6 +399,23 @@ fn test_quiet_cache() {
.stdout(is_empty());
}
+#[test]
+fn test_clear_only_pages_directory() {
+ let testenv = TestEnv::new().install_default_cache();
+ testenv
+ .command()
+ .args(["--clear-cache"])
+ .assert()
+ .success()
+ .stderr(contains(format!(
+ "Successfully cleared cache at `{}`.",
+ testenv.cache_dir().join(TLDR_PAGES_DIR).to_str().unwrap(),
+ )));
+
+ assert!(testenv.cache_dir().is_dir());
+ assert!(!testenv.cache_dir().join(TLDR_PAGES_DIR).exists());
+}
+
#[test]
fn test_warn_invalid_tls_backend() {
let testenv = TestEnv::new()
@@ -311,6 +445,21 @@ fn test_quiet_failures() {
.stdout(is_empty());
}
+#[test]
+fn test_quiet_missing_cache() {
+ let testenv = TestEnv::new();
+
+ for args in [["--list", "--quiet"], ["sl", "--quiet"]] {
+ testenv
+ .command()
+ .args(args)
+ .assert()
+ .failure()
+ .stdout(is_empty())
+ .stderr(is_empty());
+ }
+}
+
#[test]
fn test_quiet_old_cache() {
let testenv = TestEnv::new().install_default_cache();
@@ -336,6 +485,26 @@ fn test_quiet_old_cache() {
.stderr(contains("The cache hasn't been updated for ").not());
}
+#[test]
+fn test_warn_cache_age_never() {
+ let testenv = TestEnv::new().install_default_cache();
+
+ filetime::set_file_mtime(
+ testenv.cache_dir().join(TLDR_PAGES_DIR),
+ filetime::FileTime::from_unix_time(1, 0),
+ )
+ .unwrap();
+
+ testenv.append_to_config("[updates]\nwarn_cache_age = \"never\"\n");
+
+ testenv
+ .command()
+ .args(["which"])
+ .assert()
+ .success()
+ .stderr(contains("The cache hasn't been updated for ").not());
+}
+
#[cfg_attr(feature = "ignore-online-tests", ignore = "online test")]
#[test]
fn test_create_cache_directory_path() {
@@ -356,38 +525,59 @@ fn test_create_cache_directory_path() {
.assert()
.success()
.stderr(contains(format!(
- "Successfully created cache directory path `{}`.",
- internal_cache_dir.to_str().unwrap()
+ "Successfully created cache directory `{}`.",
+ internal_cache_dir.join(TLDR_PAGES_DIR).to_str().unwrap()
)))
.stderr(contains("Successfully updated cache."));
assert!(internal_cache_dir.is_dir());
}
-#[cfg_attr(feature = "ignore-online-tests", ignore = "online test")]
#[test]
fn test_cache_location_not_a_directory() {
- let testenv = TestEnv::new().remove_initial_config();
+ let testenv = TestEnv::new();
let cache_dir = &testenv.cache_dir();
- let internal_file = cache_dir.join("internal");
- File::create(&internal_file).unwrap();
-
- testenv.append_to_config(format!(
- "directories.cache_dir = '{}'\n",
- internal_file.to_str().unwrap()
- ));
+ File::create(cache_dir.join(TLDR_PAGES_DIR)).unwrap();
testenv
.command()
- .arg("--update")
+ .arg("--list")
.assert()
.failure()
.stderr(contains(format!(
- "Cache directory path `{}` is not a directory",
- internal_file.display(),
+ "Cache directory `{}` exists, but is not a directory.",
+ cache_dir.join(TLDR_PAGES_DIR).display(),
)));
}
+#[cfg(unix)]
+#[test]
+fn test_cache_location_permission_denied() {
+ use std::os::unix::fs::PermissionsExt;
+
+ let testenv = TestEnv::new().install_default_cache();
+
+ testenv
+ .command()
+ .arg("--list")
+ .assert()
+ .success()
+ .stderr(contains("Permission denied").not());
+
+ // Make cache directory unreadable
+ let cache_dir = testenv.cache_dir();
+ let mut permissions = cache_dir.metadata().unwrap().permissions();
+ permissions.set_mode(0o0);
+ fs::set_permissions(cache_dir, permissions).unwrap();
+
+ testenv
+ .command()
+ .arg("--list")
+ .assert()
+ .failure()
+ .stderr(contains("Permission denied"));
+}
+
#[test]
fn test_cache_location_source() {
let testenv = TestEnv::new().remove_initial_config();
@@ -438,8 +628,9 @@ fn test_setup_seed_config() {
.failure()
.stderr(contains("A configuration file already exists"));
- let testenv = testenv.remove_initial_config();
+ assert!(testenv.config_dir().join("config.toml").is_file());
+ let testenv = testenv.remove_initial_config();
testenv
.command()
.args(["--seed-config"])
@@ -448,6 +639,48 @@ fn test_setup_seed_config() {
.stderr(contains("Successfully created seed config file here"));
assert!(testenv.config_dir().join("config.toml").is_file());
+
+ // Create parent directories as needed for the default config path.
+ fs::remove_dir_all(testenv.config_dir()).unwrap();
+ testenv
+ .command()
+ .args(["--seed-config"])
+ .assert()
+ .success()
+ .stderr(contains("Successfully created seed config file here"));
+
+ assert!(testenv.config_dir().join("config.toml").is_file());
+
+ // Write the default config to --config-path if specified by the user
+ // at the same time.
+ let custom_config_path = testenv.config_dir().join("config_custom.toml");
+ testenv
+ .command()
+ .args([
+ "--seed-config",
+ "--config-path",
+ custom_config_path.to_str().unwrap(),
+ ])
+ .assert()
+ .success()
+ .stderr(contains("Successfully created seed config file here"));
+
+ assert!(custom_config_path.is_file());
+
+ // DON'T create parent directories for a custom config path.
+ fs::remove_dir_all(testenv.config_dir()).unwrap();
+ testenv
+ .command()
+ .args([
+ "--seed-config",
+ "--config-path",
+ custom_config_path.to_str().unwrap(),
+ ])
+ .assert()
+ .failure()
+ .stderr(contains("Could not create config file"));
+
+ assert!(!custom_config_path.is_file());
}
#[test]
@@ -504,11 +737,41 @@ fn test_os_specific_page() {
.success();
}
+#[test]
+fn test_config_platforms() {
+ let testenv = TestEnv::new();
+ testenv.add_os_entry("sunos", "sunos-command", "");
+
+ let set_config_platforms = |platforms| {
+ testenv.delete_config();
+ testenv.init_config();
+ testenv.append_to_config(format!("search.platforms = {platforms}"));
+ };
+
+ // By default all platforms are searched
+ testenv.command().arg("sunos-command").assert().success();
+
+ set_config_platforms("[]");
+ testenv.command().arg("sunos-command").assert().failure();
+
+ set_config_platforms("['linux']");
+ testenv.command().arg("sunos-command").assert().failure();
+
+ set_config_platforms("['sunos']");
+ testenv.command().arg("sunos-command").assert().success();
+
+ set_config_platforms("['linux', 'all']");
+ testenv.command().arg("sunos-command").assert().success();
+
+ set_config_platforms("['current', 'all']");
+ testenv.command().arg("sunos-command").assert().success();
+}
+
#[test]
fn test_markdown_rendering() {
let testenv = TestEnv::new().install_default_cache();
- let expected = include_str!("cache/pages/common/which.md");
+ let expected = include_str!("cache/pages.en/common/which.md");
testenv
.command()
.args(["--raw", "which"])
@@ -570,6 +833,24 @@ fn test_rendering_color_never() {
);
}
+/// An end-to-end integration test for the indent config option
+#[test]
+fn test_rendering_with_indentation() {
+ let testenv = TestEnv::new().install_default_cache();
+ let expected_custom_indentation = include_str!("rendered/inkscape-compact-no-color.expected");
+
+ // Configure to set base and command indents
+ testenv.append_to_config("display.indent.base = 3\n");
+ testenv.append_to_config("display.indent.command = 1\n");
+
+ testenv
+ .command()
+ .args(["--color", "never", "inkscape-v2"])
+ .assert()
+ .success()
+ .stdout(diff(expected_custom_indentation));
+}
+
#[test]
fn test_rendering_i18n() {
_test_correct_rendering(
@@ -596,6 +877,42 @@ fn test_correct_rendering_with_config() {
.stdout(diff(expected));
}
+/// An end-to-end integration test for rendering with show_title config option enabled.
+#[test]
+fn test_show_title_config() {
+ // Test that default behavior without show_title shows no title
+ let testenv = TestEnv::new().install_default_cache();
+ let expected_no_title = include_str!("rendered/inkscape-default.expected");
+
+ testenv
+ .command()
+ .args(["--color", "always", "inkscape-v2"])
+ .assert()
+ .success()
+ .stdout(diff(expected_no_title));
+
+ // Configure to enable show_title
+ testenv.append_to_config("display.show_title = true\n");
+
+ let expected_no_color = include_str!("rendered/inkscape-with-title-no-color.expected");
+
+ testenv
+ .command()
+ .args(["inkscape-v2"])
+ .assert()
+ .success()
+ .stdout(diff(expected_no_color));
+
+ let expected = include_str!("rendered/inkscape-with-title.expected");
+
+ testenv
+ .command()
+ .args(["--color", "always", "inkscape-v2"])
+ .assert()
+ .success()
+ .stdout(diff(expected));
+}
+
#[test]
fn test_spaces_find_command() {
let testenv = TestEnv::new().install_default_cache();
@@ -709,6 +1026,14 @@ fn test_macos_is_alias_for_osx() {
.args(["--platform", "osx", "--list"])
.assert()
.stdout("maconly\n");
+
+ testenv.append_to_config("search.platforms = ['osx']\n");
+ testenv.command().arg("--list").assert().stdout("maconly\n");
+
+ testenv.delete_config();
+ testenv.init_config();
+ testenv.append_to_config("search.platforms = ['macos']\n");
+ testenv.command().arg("--list").assert().stdout("maconly\n");
}
#[test]
@@ -727,6 +1052,89 @@ fn test_common_platform_is_used_as_fallback() {
.success();
}
+#[test]
+fn test_search_language_precedence() {
+ let testenv = TestEnv::new();
+ for lang in ["en", "de", "it", "fr", "pl", "nl"] {
+ testenv.add_lang_entry(lang, lang, "");
+ }
+
+ #[expect(clippy::type_complexity)]
+ let run = |cases: &[(Vec<(&str, &str)>, Vec<&str>, &str)]| {
+ for (extra_env, extra_args, expected) in cases {
+ let mut cmd = testenv.command();
+ for (key, value) in extra_env {
+ cmd.env(key, value);
+ }
+ cmd.args(extra_args);
+ cmd.arg("--list");
+ cmd.assert().success().stdout(eq(*expected));
+ }
+ };
+
+ let env_cases = &[
+ (vec![], vec![], "en\n"),
+ (vec![("LANGUAGE", "de:it")], vec![], "en\n"),
+ (
+ vec![("LANG", "fr"), ("LANGUAGE", "de:it")],
+ vec![],
+ "de\nen\nfr\nit\n",
+ ),
+ (
+ vec![("LANG", "fr"), ("LANGUAGE", "de:it")],
+ vec!["--language", "pl"],
+ "pl\n",
+ ),
+ ];
+ run(env_cases);
+
+ // Environment is only used when config setting is not set
+ testenv.append_to_config("search.languages = ['nl']\n");
+ let config_cases = &[
+ (vec![], vec![], "nl\n"),
+ (vec![("LANGUAGE", "de:it")], vec![], "nl\n"),
+ (vec![("LANG", "fr"), ("LANGUAGE", "de:it")], vec![], "nl\n"),
+ (
+ vec![("LANG", "fr"), ("LANGUAGE", "de:it")],
+ vec!["--language", "pl"],
+ "pl\n",
+ ),
+ ];
+ run(config_cases);
+
+ // The above update setting does not change anything
+ testenv.append_to_config("updates.download_languages = ['cz']");
+ run(config_cases);
+ testenv.delete_config();
+ testenv.init_config();
+ testenv.append_to_config("updates.download_languages = ['cz']");
+ run(env_cases);
+}
+
+#[cfg_attr(feature = "ignore-online-tests", ignore = "online test")]
+#[test]
+fn test_update_language_arg() {
+ let testenv = TestEnv::new();
+ testenv
+ .command()
+ .env("LANG", "it")
+ .arg("--update")
+ .assert()
+ .success()
+ .stderr(contains("it"))
+ .stderr(contains("en"));
+
+ testenv
+ .command()
+ .env("LANG", "en")
+ .args(["--language", "it"])
+ .arg("--update")
+ .assert()
+ .success()
+ .stderr(contains("it"))
+ .stderr(contains("en").not());
+}
+
#[test]
fn test_list_flag_rendering() {
let testenv = TestEnv::new().write_custom_pages_config();
@@ -882,6 +1290,19 @@ fn test_autoupdate_cache() {
check_cache_updated(false);
}
+/// Regression test: `--no-auto-update` should be usable together with `--list`,
+/// since the auto-update gate in `main.rs` also applies to `--list`.
+#[test]
+fn test_no_auto_update_with_list() {
+ let testenv = TestEnv::new().install_default_cache();
+
+ testenv
+ .command()
+ .args(["--list", "--no-auto-update"])
+ .assert()
+ .success();
+}
+
/// End-end test to ensure .page.md files overwrite pages in cache_dir
#[test]
fn test_custom_page_overwrites() {
@@ -892,7 +1313,7 @@ fn test_custom_page_overwrites() {
// Add .page.md file to custom_pages_dir
testenv.add_page_entry(
"inkscape-v2",
- include_str!("cache/pages/common/inkscape-v2.md"),
+ include_str!("cache/pages.en/common/inkscape-v2.md"),
);
// Load expected output
@@ -935,7 +1356,7 @@ fn test_custom_patch_does_not_append_to_custom() {
// In addition to the page in the cache, add the same page as a custom page.
testenv.add_page_entry(
"inkscape-v2",
- include_str!("cache/pages/common/inkscape-v2.md"),
+ include_str!("cache/pages.en/common/inkscape-v2.md"),
);
// Load expected output
@@ -998,7 +1419,7 @@ fn test_raw_render_file() {
let path = testenv
.cache_dir()
.join(TLDR_PAGES_DIR)
- .join("pages/common/inkscape-v1.md");
+ .join("pages.en/common/inkscape-v1.md");
let mut args = vec!["--color", "never", "-f", &path.to_str().unwrap()];
// Default render
@@ -1018,7 +1439,7 @@ fn test_raw_render_file() {
.args(&args)
.assert()
.success()
- .stdout(diff(include_str!("cache/pages/common/inkscape-v1.md")));
+ .stdout(diff(include_str!("cache/pages.en/common/inkscape-v1.md")));
}
fn touch_custom_page(testenv: &TestEnv) {
@@ -1080,3 +1501,68 @@ fn test_custom_pages_dir_is_not_dir() {
.assert()
.failure();
}
+
+mod placeholder_format {
+ use super::*;
+
+ #[test]
+ fn default_long() {
+ let testenv = TestEnv::new().install_default_cache();
+ testenv
+ .command()
+ .args(["--color=always", "playerctl"])
+ .assert()
+ .success()
+ .stdout(eq(include_str!("rendered/playerctl-long.expected")));
+ }
+
+ #[test]
+ fn config() {
+ let cases = [
+ ("short", include_str!("rendered/playerctl-short.expected")),
+ ("long", include_str!("rendered/playerctl-long.expected")),
+ ("both", include_str!("rendered/playerctl-both.expected")),
+ ];
+ for (setting, expected) in cases {
+ let testenv = TestEnv::new().install_default_cache();
+ testenv.append_to_config(format!("display.placeholder_format = \"{setting}\"\n"));
+ testenv
+ .command()
+ .args(["--color=always", "playerctl"])
+ .assert()
+ .success()
+ .stdout(eq(expected));
+ }
+ }
+
+ #[test]
+ fn cli() {
+ let testenv = TestEnv::new().install_default_cache();
+ testenv.append_to_config("display.placeholder_format = \"both\"\n");
+ testenv
+ .command()
+ .args(["--color=always", "--short-options", "playerctl"])
+ .assert()
+ .success()
+ .stdout(eq(include_str!("rendered/playerctl-short.expected")));
+
+ testenv
+ .command()
+ .args(["--color=always", "--long-options", "playerctl"])
+ .assert()
+ .success()
+ .stdout(eq(include_str!("rendered/playerctl-long.expected")));
+
+ testenv
+ .command()
+ .args([
+ "--color=always",
+ "--short-options",
+ "--long-options",
+ "playerctl",
+ ])
+ .assert()
+ .success()
+ .stdout(eq(include_str!("rendered/playerctl-both.expected")));
+ }
+}
diff --git a/tests/rendered/apt.ja.expected b/tests/rendered/apt.ja.expected
index 22424e3..e79bf7e 100644
--- a/tests/rendered/apt.ja.expected
+++ b/tests/rendered/apt.ja.expected
@@ -5,33 +5,33 @@
[32m利用可能なパーケージとバージョンのリストの更新（他の`apt`コマンドの前での実行を推奨）:[0m
-[36m [0m[36msudo [0m[36mapt[0m[36m update[0m
+ [36msudo [0m[36mapt[0m[36m update[0m
[32m指定されたパッケージの検索:[0m
-[36m [0m[36mapt[0m[36m search [0m[4;36mパッケージ[0m
+ [36mapt[0m[36m search [0m[4;36mパッケージ[0m
[32mパッケージの情報を出力:[0m
-[36m [0m[36mapt[0m[36m show [0m[4;36mパッケージ[0m
+ [36mapt[0m[36m show [0m[4;36mパッケージ[0m
[32mパッケージのインストール、または利用可能な最新バージョンに更新:[0m
-[36m [0m[36msudo [0m[36mapt[0m[36m install [0m[4;36mパッケージ[0m
+ [36msudo [0m[36mapt[0m[36m install [0m[4;36mパッケージ[0m
[32mパッケージの削除（`sudo apt remove --purge`の場合設定ファイルも削除）:[0m
-[36m [0m[36msudo [0m[36mapt[0m[36m remove [0m[4;36mパッケージ[0m
+ [36msudo [0m[36mapt[0m[36m remove [0m[4;36mパッケージ[0m
[32mインストールされている全てのパッケージを最新のバージョンにアップグレード:[0m
-[36m [0m[36msudo [0m[36mapt[0m[36m upgrade[0m
+ [36msudo [0m[36mapt[0m[36m upgrade[0m
[32mインストールできるすべてのパッケージを表示:[0m
-[36m [0m[36mapt[0m[36m list[0m
+ [36mapt[0m[36m list[0m
[32mインストールされた全てのパッケージを表示（依存関係も表示）:[0m
-[36m [0m[36mapt[0m[36m list --installed[0m
+ [36mapt[0m[36m list --installed[0m
diff --git a/tests/rendered/inkscape-compact-no-color.expected b/tests/rendered/inkscape-compact-no-color.expected
new file mode 100644
index 0000000..473bbe9
--- /dev/null
+++ b/tests/rendered/inkscape-compact-no-color.expected
@@ -0,0 +1,32 @@
+
+ An SVG (Scalable Vector Graphics) editing program.
+ Use -z to not open the GUI and only process files in the console.
+
+ Open an SVG file in the Inkscape GUI:
+
+ inkscape filename.svg
+
+ Export an SVG file into a bitmap with the default format (PNG) and the default resolution (90 DPI):
+
+ inkscape filename.svg -e filename.png
+
+ Export an SVG file into a bitmap of 600x400 pixels (aspect ratio distortion may occur):
+
+ inkscape filename.svg -e filename.png -w 600 -h 400
+
+ Export a single object, given its ID, into a bitmap:
+
+ inkscape filename.svg -i id -e object.png
+
+ Export an SVG document to PDF, converting all texts to paths:
+
+ inkscape filename.svg | inkscape | inkscape --export-pdf=inkscape.pdf | inkscape | inkscape --export-text-to-path
+
+ Duplicate the object with id="path123", rotate the duplicate 90 degrees, save the file, and quit Inkscape:
+
+ inkscape filename.svg --select=path123 --verb=EditDuplicate --verb=ObjectRotate90 --verb=FileSave --verb=FileQuit
+
+ Some invalid command just to test the correct highlighting of the command name:
+
+ inkscape --use-inkscape=v3.0 file
+
diff --git a/tests/rendered/inkscape-default.expected b/tests/rendered/inkscape-default.expected
index da909f2..5b91247 100644
--- a/tests/rendered/inkscape-default.expected
+++ b/tests/rendered/inkscape-default.expected
@@ -4,29 +4,29 @@
[32mOpen an SVG file in the Inkscape GUI:[0m
-[36m [0m[36minkscape[0m[36m [0m[4;36mfilename.svg[0m
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m
[32mExport an SVG file into a bitmap with the default format (PNG) and the default resolution (90 DPI):[0m
-[36m [0m[36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m -e [0m[4;36mfilename.png[0m
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m -e [0m[4;36mfilename.png[0m
[32mExport an SVG file into a bitmap of 600x400 pixels (aspect ratio distortion may occur):[0m
-[36m [0m[36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m -e [0m[4;36mfilename.png[0m[36m -w [0m[4;36m600[0m[36m -h [0m[4;36m400[0m
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m -e [0m[4;36mfilename.png[0m[36m -w [0m[4;36m600[0m[36m -h [0m[4;36m400[0m
[32mExport a single object, given its ID, into a bitmap:[0m
-[36m [0m[36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m -i [0m[4;36mid[0m[36m -e [0m[4;36mobject.png[0m
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m -i [0m[4;36mid[0m[36m -e [0m[4;36mobject.png[0m
[32mExport an SVG document to PDF, converting all texts to paths:[0m
-[36m [0m[36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m | [0m[36minkscape[0m[36m | [0m[36minkscape[0m[36m --export-pdf=[0m[4;36minkscape.pdf[0m[36m | [0m[36minkscape[0m[36m | [0m[36minkscape[0m[36m --export-text-to-path[0m
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m | [0m[36minkscape[0m[36m | [0m[36minkscape[0m[36m --export-pdf=[0m[4;36minkscape.pdf[0m[36m | [0m[36minkscape[0m[36m | [0m[36minkscape[0m[36m --export-text-to-path[0m
[32mDuplicate the object with id="path123", rotate the duplicate 90 degrees, save the file, and quit Inkscape:[0m
-[36m [0m[36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m --select=path123 --verb=EditDuplicate --verb=ObjectRotate90 --verb=FileSave --verb=FileQuit[0m
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m --select=path123 --verb=EditDuplicate --verb=ObjectRotate90 --verb=FileSave --verb=FileQuit[0m
[32mSome invalid command just to test the correct highlighting of the command name:[0m
-[36m [0m[36minkscape[0m[36m --use-inkscape=v3.0 file[0m
+ [36minkscape[0m[36m --use-inkscape=v3.0 file[0m
diff --git a/tests/rendered/inkscape-with-title-no-color.expected b/tests/rendered/inkscape-with-title-no-color.expected
new file mode 100644
index 0000000..b6a4572
--- /dev/null
+++ b/tests/rendered/inkscape-with-title-no-color.expected
@@ -0,0 +1,34 @@
+
+ inkscape
+
+ An SVG (Scalable Vector Graphics) editing program.
+ Use -z to not open the GUI and only process files in the console.
+
+ Open an SVG file in the Inkscape GUI:
+
+ inkscape filename.svg
+
+ Export an SVG file into a bitmap with the default format (PNG) and the default resolution (90 DPI):
+
+ inkscape filename.svg -e filename.png
+
+ Export an SVG file into a bitmap of 600x400 pixels (aspect ratio distortion may occur):
+
+ inkscape filename.svg -e filename.png -w 600 -h 400
+
+ Export a single object, given its ID, into a bitmap:
+
+ inkscape filename.svg -i id -e object.png
+
+ Export an SVG document to PDF, converting all texts to paths:
+
+ inkscape filename.svg | inkscape | inkscape --export-pdf=inkscape.pdf | inkscape | inkscape --export-text-to-path
+
+ Duplicate the object with id="path123", rotate the duplicate 90 degrees, save the file, and quit Inkscape:
+
+ inkscape filename.svg --select=path123 --verb=EditDuplicate --verb=ObjectRotate90 --verb=FileSave --verb=FileQuit
+
+ Some invalid command just to test the correct highlighting of the command name:
+
+ inkscape --use-inkscape=v3.0 file
+
diff --git a/tests/rendered/inkscape-with-title.expected b/tests/rendered/inkscape-with-title.expected
new file mode 100644
index 0000000..7e81d41
--- /dev/null
+++ b/tests/rendered/inkscape-with-title.expected
@@ -0,0 +1,34 @@
+
+ [36minkscape[0m
+
+ An SVG (Scalable Vector Graphics) editing program.
+ Use -z to not open the GUI and only process files in the console.
+
+ [32mOpen an SVG file in the Inkscape GUI:[0m
+
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m
+
+ [32mExport an SVG file into a bitmap with the default format (PNG) and the default resolution (90 DPI):[0m
+
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m -e [0m[4;36mfilename.png[0m
+
+ [32mExport an SVG file into a bitmap of 600x400 pixels (aspect ratio distortion may occur):[0m
+
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m -e [0m[4;36mfilename.png[0m[36m -w [0m[4;36m600[0m[36m -h [0m[4;36m400[0m
+
+ [32mExport a single object, given its ID, into a bitmap:[0m
+
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m -i [0m[4;36mid[0m[36m -e [0m[4;36mobject.png[0m
+
+ [32mExport an SVG document to PDF, converting all texts to paths:[0m
+
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m | [0m[36minkscape[0m[36m | [0m[36minkscape[0m[36m --export-pdf=[0m[4;36minkscape.pdf[0m[36m | [0m[36minkscape[0m[36m | [0m[36minkscape[0m[36m --export-text-to-path[0m
+
+ [32mDuplicate the object with id="path123", rotate the duplicate 90 degrees, save the file, and quit Inkscape:[0m
+
+ [36minkscape[0m[36m [0m[4;36mfilename.svg[0m[36m --select=path123 --verb=EditDuplicate --verb=ObjectRotate90 --verb=FileSave --verb=FileQuit[0m
+
+ [32mSome invalid command just to test the correct highlighting of the command name:[0m
+
+ [36minkscape[0m[36m --use-inkscape=v3.0 file[0m
+
diff --git a/tests/rendered/playerctl-both.expected b/tests/rendered/playerctl-both.expected
new file mode 100644
index 0000000..1f49457
--- /dev/null
+++ b/tests/rendered/playerctl-both.expected
@@ -0,0 +1,32 @@
+
+ Control media players via MPRIS.
+ More information: .
+
+ [32mToggle play:[0m
+
+ [36mplayerctl[0m[36m play-pause[0m
+
+ [32mSkip to the next track:[0m
+
+ [36mplayerctl[0m[36m next[0m
+
+ [32mGo back to the previous track:[0m
+
+ [36mplayerctl[0m[36m previous[0m
+
+ [32mList all players:[0m
+
+ [36mplayerctl[0m[36m [0m[36m[-l|--list-all][0m
+
+ [32mSend a command to a specific player:[0m
+
+ [36mplayerctl[0m[36m [0m[36m[-p|--player][0m[36m [0m[4;36mplayer_name[0m[36m [0m[4;36mplay-pause|next|previous|...[0m
+
+ [32mSend a command to all players:[0m
+
+ [36mplayerctl[0m[36m [0m[36m[-a|--all-players][0m[36m [0m[4;36mplay-pause|next|previous|...[0m
+
+ [32mDisplay metadata about the current track:[0m
+
+ [36mplayerctl[0m[36m metadata [0m[36m[-f|--format][0m[36m "[0m[4;36mNow playing: {{artist}} - {{album}} - {{title}}[0m[36m"[0m
+
diff --git a/tests/rendered/playerctl-long.expected b/tests/rendered/playerctl-long.expected
new file mode 100644
index 0000000..4d0ad10
--- /dev/null
+++ b/tests/rendered/playerctl-long.expected
@@ -0,0 +1,32 @@
+
+ Control media players via MPRIS.
+ More information: .
+
+ [32mToggle play:[0m
+
+ [36mplayerctl[0m[36m play-pause[0m
+
+ [32mSkip to the next track:[0m
+
+ [36mplayerctl[0m[36m next[0m
+
+ [32mGo back to the previous track:[0m
+
+ [36mplayerctl[0m[36m previous[0m
+
+ [32mList all players:[0m
+
+ [36mplayerctl[0m[36m [0m[36m--list-all[0m
+
+ [32mSend a command to a specific player:[0m
+
+ [36mplayerctl[0m[36m [0m[36m--player[0m[36m [0m[4;36mplayer_name[0m[36m [0m[4;36mplay-pause|next|previous|...[0m
+
+ [32mSend a command to all players:[0m
+
+ [36mplayerctl[0m[36m [0m[36m--all-players[0m[36m [0m[4;36mplay-pause|next|previous|...[0m
+
+ [32mDisplay metadata about the current track:[0m
+
+ [36mplayerctl[0m[36m metadata [0m[36m--format[0m[36m "[0m[4;36mNow playing: {{artist}} - {{album}} - {{title}}[0m[36m"[0m
+
diff --git a/tests/rendered/playerctl-short.expected b/tests/rendered/playerctl-short.expected
new file mode 100644
index 0000000..f2f5511
--- /dev/null
+++ b/tests/rendered/playerctl-short.expected
@@ -0,0 +1,32 @@
+
+ Control media players via MPRIS.
+ More information: .
+
+ [32mToggle play:[0m
+
+ [36mplayerctl[0m[36m play-pause[0m
+
+ [32mSkip to the next track:[0m
+
+ [36mplayerctl[0m[36m next[0m
+
+ [32mGo back to the previous track:[0m
+
+ [36mplayerctl[0m[36m previous[0m
+
+ [32mList all players:[0m
+
+ [36mplayerctl[0m[36m [0m[36m-l[0m
+
+ [32mSend a command to a specific player:[0m
+
+ [36mplayerctl[0m[36m [0m[36m-p[0m[36m [0m[4;36mplayer_name[0m[36m [0m[4;36mplay-pause|next|previous|...[0m
+
+ [32mSend a command to all players:[0m
+
+ [36mplayerctl[0m[36m [0m[36m-a[0m[36m [0m[4;36mplay-pause|next|previous|...[0m
+
+ [32mDisplay metadata about the current track:[0m
+
+ [36mplayerctl[0m[36m metadata [0m[36m-f[0m[36m "[0m[4;36mNow playing: {{artist}} - {{album}} - {{title}}[0m[36m"[0m
+