Improve documentation (#529)

docs/config_file_example.yaml

@@ -0,0 +1,28 @@
+# THIS IS EXPERIMENTAL
+# the config file schema may change at any time
+
+style:
+  tag:
+    color: cyan # text color. possible values: https://bit.ly/3gloNNI
+    width_percentage: 26 # column width relative to the terminal window
+    min_width: 20 # minimum column width as number of characters
+  comment:
+    color: blue
+    width_percentage: 42
+    min_width: 45
+  snippet:
+    color: white
+
+finder:
+  command: fzf # equivalent to the --finder option
+  # overrides: --tac # equivalent to the --fzf-overrides option
+  # overrides_var: --tac # equivalent to the --fzf-overrides-var option
+
+# cheats:
+  # path: /path/to/some/dir # equivalent to the --path option
+
+# search:
+  # tags: git,!checkout # equivalent to the --tag-rules option
+
+shell:
+  command: bash # shell used for shell out. possible values: bash, zsh, dash, ...

docs/customization.md

@@ -9,30 +9,11 @@ Customization
 
 You can change the [color scheme](https://github.com/junegunn/fzf/wiki/Color-schemes) by [overriding fzf options](#overriding-fzf-options).
 
-In addition, you can change the text color for each column by setting the following environment variables:
+In addition, you can change the text color for each column by properly configuring *navi*'s `config.yaml`. Please check `navi --help` for more instructions.
-- `$NAVI_TAG_COLOR`
-- `$NAVI_COMMENT_COLOR`
-- `$NAVI_SNIPPET_COLOR`
-
-The values go [from 0 to 15](https://github.com/redox-os/termion/blob/189222555ef92a29de366f96d2a067b3a920fc24/src/color.rs#L62-L77).
-
-For example, if you add the following to your .bashrc-like file, the comment color will be yellow:
-```sh
-export NAVI_COMMENT_COLOR=3
-```
 
 ### Resizing columns
 
-You can change the column widths by setting the following environment variables:
+You can change the column widths by properly configuring *navi*'s `config.yaml`. Please check `navi --help` for more instructions.
-- `$NAVI_TAG_WIDTH`
-- `$NAVI_COMMENT_WIDTH`
-
-The values go from 0 to 100 and represent the percentage the column will occupy.
-
-For example, if you add the following to your .bashrc-like file, the comment column will be very small:
-```sh
-export NAVI_COMMENT_WIDTH=5
-```
 
 ### Overriding fzf options
 
@@ -56,3 +37,5 @@ export NAVI_FZF_OVERRIDES_VAR='--height 3'
 # if you want to override for all cases
 FZF_DEFAULT_OPTS="--height 3" navi
 ```
+
+In addition, this can be set by properly configuring *navi*'s `config.yaml`. Please check `navi --help` for more instructions.

src/actor.rs

@@ -180,7 +180,6 @@ fn replace_variables_from_snippet(snippet: &str, tags: &str, variables: Variable
     Ok(interpolated_snippet)
 }
 
-// TODO: make it depend on less inputs
 pub fn act(
     extractions: Result<extractor::Output>,
     files: Vec<String>,

src/config/cli.rs

@@ -11,7 +11,7 @@ use std::str::FromStr;
 const FINDER_POSSIBLE_VALUES: &[&str] = &[&"fzf", &"skim"];
 const WIDGET_POSSIBLE_VALUES: &[&str] = &[&"bash", &"zsh", &"fish"];
 const FUNC_POSSIBLE_VALUES: &[&str] = &[&"url::open", &"welcome", &"widget::last_command", &"map::expand"];
-const INFO_POSSIBLE_VALUES: &[&str] = &[&"cheats-path", "config-path"];
+const INFO_POSSIBLE_VALUES: &[&str] = &[&"cheats-path", "config-path", "config-example"];
 
 impl FromStr for Shell {
     type Err = &'static str;
@@ -46,6 +46,7 @@ impl FromStr for Info {
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         match s {
             "cheats-path" => Ok(Info::CheatsPath),
+            "config-example" => Ok(Info::ConfigExample),
             "config-path" => Ok(Info::ConfigPath),
             _ => Err("no match"),
         }
@@ -57,9 +58,21 @@ impl FromStr for Info {
     Please refer to https://github.com/denisidoro/navi
 
 MORE ENVIRONMENT VARIABLES:
-    NAVI_TAG_WIDTH                               # tag column width as window integer %
+    NAVI_CONFIG            # path to config file
-    NAVI_COMMENT_WIDTH                           # comment column width as window integer %
+    NAVI_CONFIG_YAML       # config file content
-    NAVI_SHELL                                   # shell used in shell outs
+
+CONFIG FILE:
+    By default it's located in:
+       navi info config-path
+
+    You can generate a config file by running:
+       navi info config-example > "$(navi info config-path)"
+     
+    Please check the generated config file for more info
+
+FEATURE STABILITY:
+    experimental           # may be removed or changed at any time
+    deprecated             # may be removed in 3 months after first being deprecated
 
 EXAMPLES:
     navi                                         # default behavior
@@ -78,8 +91,6 @@ EXAMPLES:
     navi --fzf-overrides-var '--no-select-1'     # same, but for variable selection
     navi --fzf-overrides '--nth 1,2'             # only consider the first two columns for search
     navi --fzf-overrides '--no-exact'            # use looser search algorithm
-    NAVI_SHELL=dash navi                         # use dash in shell outs
-    NAVI_TAG_WIDTH=30 NAVI_COMMENT_WIDTH=40 navi # customize column widths
     navi --tag-rules='git,!checkout'             # show non-checkout git snippets only"#)]
 #[clap(setting = AppSettings::ColorAuto)]
 #[clap(setting = AppSettings::ColoredHelp)]

src/config/mod.rs

@@ -6,7 +6,6 @@ use crate::finder::FinderChoice;
 
 use crate::terminal::style::Color;
 pub use cli::*;
-use std::process;
 
 use env::EnvConfig;
 use yaml::YamlConfig;
@@ -23,17 +22,14 @@ pub struct Config {
 impl Config {
     pub fn new() -> Self {
         let env = EnvConfig::new();
-        match YamlConfig::get(&env) {
+        let yaml = YamlConfig::get(&env).unwrap_or_else(|e| {
-            Ok(yaml) => Self {
-                yaml,
-                env,
-                clap: ClapConfig::new(),
-            },
-            Err(e) => {
             eprintln!("Error parsing config file: {}", e);
-                process::exit(42)
+            eprintln!("Fallbacking to default one...");
-            }
+            eprintln!();
-        }
+            YamlConfig::default()
+        });
+        let clap = ClapConfig::new();
+        Self { yaml, clap, env }
     }
 
     pub fn best_match(&self) -> bool {

src/config/yaml.rs

@@ -9,6 +9,7 @@ use std::convert::TryFrom;
 use std::io::BufReader;
 use std::path::Path;
 use std::path::PathBuf;
+use std::str::FromStr;
 
 #[derive(Deserialize)]
 pub struct Color(#[serde(deserialize_with = "color_deserialize")] TerminalColor);
@@ -47,11 +48,21 @@ pub struct Style {
 #[derive(Deserialize)]
 #[serde(default)]
 pub struct Finder {
+    #[serde(deserialize_with = "finder_deserialize")]
     pub command: FinderChoice,
     pub overrides: Option<String>,
     pub overrides_var: Option<String>,
 }
 
+fn finder_deserialize<'de, D>(deserializer: D) -> Result<FinderChoice, D::Error>
+where
+    D: de::Deserializer<'de>,
+{
+    let s: String = Deserialize::deserialize(deserializer)?;
+    FinderChoice::from_str(s.to_lowercase().as_str())
+        .map_err(|_| de::Error::custom(format!("Failed to deserialize finder: {}", s)))
+}
+
 #[derive(Deserialize)]
 #[serde(default)]
 pub struct Cheats {

src/handler/info.rs

@@ -6,12 +6,14 @@ use anyhow::Result;
 pub enum Info {
     CheatsPath,
     ConfigPath,
+    ConfigExample,
 }
 
 pub fn main(info: &Info) -> Result<()> {
     match info {
         Info::CheatsPath => println!("{}", pathbuf_to_string(&filesystem::default_cheat_pathbuf()?)?),
         Info::ConfigPath => println!("{}", pathbuf_to_string(&filesystem::default_config_pathbuf()?)?),
+        Info::ConfigExample => println!("{}", include_str!("../../docs/config_file_example.yaml")),
     }
     Ok(())
 }

src/handler/preview.rs

@@ -13,8 +13,6 @@ fn extract_elements(argstr: &str) -> (&str, &str, &str) {
 }
 
 pub fn main(line: &str) -> Result<()> {
-    // dbg!(CONFIG.comment_color());
-
     let (tags, comment, snippet) = extract_elements(line);
 
     println!(