Merge pull request 'Implement config file' (#15) from implement-config into main

Reviewed-on: https://codeberg.org/lukeflo/bibiman/pulls/15

1 files changed, 125 insertions, 31 deletions

diff --git a/README.md b/README.md
index 8285e37..6907af4 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 <div align="center">
 
-# Bibiman
+# Bibiman<a name="bibiman"></a>
 
 <!-- [![noMSgithub badge](https://nogithub.codeberg.page/badge.svg)](https://nogithub.codeberg.page/) -->
 
@@ -8,7 +8,28 @@
 
 </div>
 
-## TL;DR
+<!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=1 -->
+
+- [Bibiman](#bibiman)
+  - [TL;DR](#tldr)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Configuration](#configuration)
+    - [Location of Config File](#location-of-config-file)
+    - [General Configuration](#general-configuration)
+    - [Color Configuration](#color-configuration)
+  - [Features](#features)
+  - [Keybindings](#keybindings)
+  - [Search](#search)
+  - [Edit bib entry](#edit-bib-entry)
+  - [Open connected files or links](#open-connected-files-or-links)
+  - [Issues and code improvement](#issues-and-code-improvement)
+  - [Alternatives](#alternatives)
+    - [Comparison](#comparison)
+
+<!-- mdformat-toc end -->
+
+## TL;DR<a name="tldr"></a>
 
 `bibiman` is a simple terminal user interface for handling your BibLaTeX
 database as part of a terminal-based scientific workflow.
@@ -17,7 +38,7 @@ Here's a small impression how it looks and works:
 
 [![bibiman.gif](https://i.postimg.cc/d0Mb9vMY/bibiman.gif)](https://postimg.cc/zyj2JsXt)
 
-## Installation
+## Installation<a name="installation"></a>
 
 You can install `bibiman` directly from `crates.io` using `cargo`:
 
@@ -41,7 +62,7 @@ cargo install --path=. --locked
 
 ```
 
-## Usage
+## Usage<a name="usage"></a>
 
 The following arguments are possible:
 
@@ -56,6 +77,8 @@ POSITIONAL ARGS:
 FLAGS:
     -h, --help          Show this help and exit
     -v, --version       Show the version and exit
+    -c, --config-file=  Path to config file for current session needed as argument.
+                        Takes precedence over standard config file 
     --light-terminal    Enable color mode for light terminal background
 
 ```
@@ -85,45 +108,114 @@ bibman tests/multi-files/
 bibiman tests/biblatex-test.bib tests/multi-files/
 ```
 
-Furthermore, in issue #3 it was asked to enable a color customization to run
-`bibiman` also in terminal setups with light background. Thus, now it is
-possible to enable a light terminal mode with the `--light-terminal` flag. Full
-color customization is not possible right now, but maybe will be added with the
-implementation of a config file.
+## Configuration<a name="configuration"></a>
 
-Here is how the light terminal scheme looks:
+### Location of Config File<a name="location-of-config-file"></a>
 
-![bibiman-light-theme.png](https://codeberg.org/attachments/7fe9d58d-7e90-4043-9402-5e4664c4e22a)
+`bibiman` can be configured through a config file. The standard location is the
+user's config dir following the XDG scheme. On Linux systems this defaults to:
 
-## Features
+```bash
+# XDG scheme:
+$XDG_CONFIG_HOME/bibiman/bibiman.toml
+
+# Fallback:
+$HOME/.config/bibiman/bibiman.toml
+```
+
+You can set a custom config file through the CLI (`-c`/`--config-file=` flag)
+which takes precedence over the standard one for the active session:
+
+```bash
+bibiman --config-file="/path/to/temporary/config"
+```
+
+### General Configuration<a name="general-configuration"></a>
+
+The following general values can be set through the config file:
+
+```toml
+[general]
+# Default files/dirs which are loaded on startup
+# Use absolute paths (~ for HOME works). Otherwise, loading might not work.
+bibfiles = [ "/path/to/bibfile", "path/to/dir/with/bibfiles" ]
+# Default editor to use when editing files. Arguments are possible
+editor = "vim" # with args: "vim -y"
+# Default app to open PDFs/Epubs
+pdf_opener = "xdg-open"
+# Default app to open URLs/DOIs
+url_opener = "xdg-open"
+```
+
+If no file or dir is set as `bibfiles` value, you *have to* add a path via CLI
+interface. If the `bibfiles` value is set *and* a further path (or multiple) is
+provided through the CLI call, the entries of all those files will be opened in
+the started `bibiman` session.
+
+### Color Configuration<a name="color-configuration"></a>
+
+Furthermore, it is now possible to customize the colors. The following values
+can be changed:
+
+```toml
+[colors]
+# Default values for dark-themed terminal
+main_text_color = "250"
+highlight_text_color = "254"
+entry_color = "36"
+keyword_color = "101"
+info_color = "99"
+confirm_color = "47"
+warn_color = "124"
+bar_bg_color = "234"
+popup_bg_color = "234"
+selected_row_bg_color = "237"
+```
+
+Colors can be set through three different methods:
+[ANSI color names](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html),
+[256-color indices](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) and
+[HEX codes](https://www.w3schools.com/colors/colors_hexadecimal.asp). For
+example, the following definitions are all valid:
+
+```toml
+selected_row_bg_color = "darkgray" # ANSI color name (light_black or bright_black would also work)
+selected_row_bg_color = "237" # 256-color index
+selected_row_bg_color = "#3a3a3a" # HEX code
+```
+
+To run `bibiman` with some default values for a light-colored terminal use the
+`--light-terminal` flag.
+
+## Features<a name="features"></a>
 
 These are the current features, the list will be updated:
 
 - [x] **Browse** through the bib entries using _Vim-like keybindings_ and a
-      _fuzzy search_ mode.
+  _fuzzy search_ mode.
 - [x] **Filter** the bib entries by _keywords_ (and afterwards filter further by
-      fuzzy searching).
+  fuzzy searching).
 - [x] **Edit** the current entry by opening a _terminal-based editor_ at the
-      specific line.
+  specific line.
 - [x] **Yank/Copy** the citekey of the current entry to the system clipboard.
 - [x] **Open related PDF** file (`file` BibLaTeX key) with keypress.
 - [x] **Open related URL/DOI** with keypress.
 - [x] **Scrollbar** for better navigating.
 - [x] **Sort Entries** by column (`Authors`, `Title`, `Year`, `Pubtype`), or by
-      position in bibfile.
+  position in bibfile.
 - [x] **Load multiple files** into one session.
 - [x] **Add Entry via DOI**.
+- [x] **Implement config file** for setting some default values like main
+  bibfile, PDF-opener, or editor
 - [ ] **Open related notes file** for specific entry.
-- [ ] **Implement config file** for setting some default values like main
-      bibfile, PDF-opener, or editor
 - [ ] **Support Hayagriva(`.yaml`)** format as input (_on hold for now_, because
-      the Hayagriva Yaml style doesn't offer keywords; s. issue in
-      [Hayagriva repo](https://github.com/typst/hayagriva/issues/240)).
+  the Hayagriva Yaml style doesn't offer keywords; s. issue in
+  [Hayagriva repo](https://github.com/typst/hayagriva/issues/240)).
 
 **Please feel free to suggest further features through the issue
 functionality.**
 
-## Keybindings
+## Keybindings<a name="keybindings"></a>
 
 Use the following keybindings to manage the TUI:
 
@@ -147,7 +239,7 @@ Use the following keybindings to manage the TUI:
 | `ESC`                                    | Abort search / Reset current list                        |
 | `q`, `Ctrl-c`                            | Quit TUI                                                 |
 
-## Search
+## Search<a name="search"></a>
 
 The search mode uses the `nucleo-matcher` crate. Thus, _fuzzy searching_ is
 enabled by default. You can use some special chars to alter pattern matching:
@@ -156,19 +248,21 @@ enabled by default. You can use some special chars to alter pattern matching:
 - `...$` matches literally at end of the string.
 - `'...` matches literally everywhere in string.
 
-## Edit bib entry
+## Edit bib entry<a name="edit-bib-entry"></a>
 
-For now, the TUI only supports editors set through the environment variables
-`VISUAL` and `EDITOR` in this order. The fallback solution is `vi`.
+The main editor can be set through the [config file](#general-configuration).
+Otherwise, the environment variables `VISUAL` and `EDITOR` will be used in this
+order. The last fallback solution is `vi`.
 
-I've tested the following editors (set as value of `VISUAL`):
+I've tested the following editors (set as value of `VISUAL` and through the
+config file):
 
 - [x] **Helix**: `export VISUAL="hx"`
 - [x] **Vim/Neovim**: `export VISUAL="vim/nvim"`
 - [x] **Emacs (Terminal)**: `export VISUAL="emacs -nw"`
 - [x] **Nano**: `export VISUAL="nano"`
 - [x] **Emacs (GUI)**: `export VISUAL="emacs"` (open emacs in separate window,
-      blocks the terminal running `bibiman` as long as emacs is opened)
+  blocks the terminal running `bibiman` as long as emacs is opened)
 
 Feel free to try other editors and report. Important is that the editor supports
 the argument `+..` to set the line number that the cursor should be placed at.
@@ -178,7 +272,7 @@ While this behaviour is most likely supported on UNIX-based systems (Linux,
 MacOS), it might not work under Windows. I can't test it on a Windows machine,
 thus, there might be unexpected errors with it.
 
-## Open connected files or links
+## Open connected files or links<a name="open-connected-files-or-links"></a>
 
 `bibiman` also provides the possibility to open PDFs (as value of the `file`
 BibLaTeX field), as well as DOIs and URLs.
@@ -194,12 +288,12 @@ Furthermore, DOIs have to begin with either `https://doi...` as full URL or
 `10.(...)` as regular DOI style. URLs work if they begin with either `http...`
 or with `www...`.
 
-## Issues and code improvement
+## Issues and code improvement<a name="issues-and-code-improvement"></a>
 
 This is my first Rust project and, thus, also a learning process. If you find
 any issues or code flaws, please open an issue.
 
-## Alternatives
+## Alternatives<a name="alternatives"></a>
 
 `bibiman` is a project tailored to my personal needs. I use a single main file
 for all my bib entries and want to use `bibiman` mainly as kind of
@@ -226,7 +320,7 @@ Maybe one of these might fit _your_ personal needs better:
 - [papis](https://github.com/papis/papis): Powerful CLI tool for managing
   bibliographies and documents. Has also some TUI features.
 
-### Comparison
+### Comparison<a name="comparison"></a>
 
 I compared `bibiman` only free-hand to `bibman` (Haskell) and `bibman` (Perl),
 since there is no simple benchmark test for TUIs. At least, I couldn't find one.