From 32a32e9180ef1b1df114485f1a81a9707d3ac1c1 Mon Sep 17 00:00:00 2001 From: Arijit Basu Date: Thu, 24 Jun 2021 16:47:56 +0530 Subject: [PATCH] Add more docs Also, prepare for release. --- README.md | 2 + docs/en/src/SUMMARY.md | 2 + docs/en/src/filtering.md | 87 ++++++++++++++++++++++ docs/en/src/general-config.md | 135 +++++++++++++++++++++++++++++++++- docs/en/src/sorting.md | 83 +++++++++++++++++++++ docs/en/src/upgrade-guide.md | 6 +- 6 files changed, 313 insertions(+), 2 deletions(-) create mode 100644 docs/en/src/filtering.md create mode 100644 docs/en/src/sorting.md diff --git a/README.md b/README.md index 367ede5..c319edf 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,8 @@ Table of content - [Layouts](https://arijitbasu.in/xplr/en/layouts.html) - [Node Types](https://arijitbasu.in/xplr/en/node_types.html) - [Style](https://arijitbasu.in/xplr/en/style.html) + - [Sorting](https://arijitbasu.in/xplr/en/sorting.html) + - [Filtering](https://arijitbasu.in/xplr/en/filtering.html) - [Default Key Bindings](https://arijitbasu.in/xplr/en/default-key-bindings.html) - [Plugin](https://arijitbasu.in/xplr/en/plugin.html) - [Installing Plugins](https://arijitbasu.in/xplr/en/installing-plugins.html) diff --git a/docs/en/src/SUMMARY.md b/docs/en/src/SUMMARY.md index 5422d85..bac7fff 100644 --- a/docs/en/src/SUMMARY.md +++ b/docs/en/src/SUMMARY.md @@ -12,6 +12,8 @@ A hackable, minimal, fast TUI file explorer - [Layouts](layouts.md) - [Node Types](node_types.md) - [Style](style.md) + - [Sorting](sorting.md) + - [Filtering](filtering.md) - [Default Key Bindings](default-key-bindings.md) - [Plugin](plugin.md) - [Installing Plugins](installing-plugins.md) diff --git a/docs/en/src/filtering.md b/docs/en/src/filtering.md new file mode 100644 index 0000000..e84a6b5 --- /dev/null +++ b/docs/en/src/filtering.md @@ -0,0 +1,87 @@ +Filtering +========= + +xplr supports filtering paths by different properties. The filtering mechanism +works like a pipeline, which in visible in the `Sort & filter` panel. + +Example: + +``` +rel!^. › [i]abs=~abc › [i]rel!~xyz +``` + +This line means that the nodes visible on the table will first be filtered by +the condition: *relative path does not start with `.`*, then by the condition: +*absolute path contains `abc` (case insensitive)*, and finally by the +condition: *relative path does not contain `xyz`*. + +Each part of this pipeline is called [Node Filter Applicable](#node-filter-applicable). + + +Node Filter Applicable +---------------------- + +It contains the following information: + +- [filter](#filter) +- [input](#input) + +### filter + +A filter can be one of the following: + +- "RelativePathIs" +- "RelativePathIsNot" +- "IRelativePathIs" +- "IRelativePathIsNot" +- "RelativePathDoesStartWith" +- "RelativePathDoesNotStartWith" +- "IRelativePathDoesStartWith" +- "IRelativePathDoesNotStartWith" +- "RelativePathDoesContain" +- "RelativePathDoesNotContain" +- "IRelativePathDoesContain" +- "IRelativePathDoesNotContain" +- "RelativePathDoesEndWith" +- "RelativePathDoesNotEndWith" +- "IRelativePathDoesEndWith" +- "IRelativePathDoesNotEndWith" +- "AbsolutePathIs" +- "AbsolutePathIsNot" +- "IAbsolutePathIs" +- "IAbsolutePathIsNot" +- "AbsolutePathDoesStartWith" +- "AbsolutePathDoesNotStartWith" +- "IAbsolutePathDoesStartWith" +- "IAbsolutePathDoesNotStartWith" +- "AbsolutePathDoesContain" +- "AbsolutePathDoesNotContain" +- "IAbsolutePathDoesContain" +- "IAbsolutePathDoesNotContain" +- "AbsolutePathDoesEndWith" +- "AbsolutePathDoesNotEndWith" +- "IAbsolutePathDoesEndWith" +- "IAbsolutePathDoesNotEndWith" + + +TODO: document each + +### input + +Type: string + +The input for the condition. + + +Example: +-------- + +```lua +ToggleNodeFilter = { + filter = "RelativePathDoesNotStartWith", + input = "." +} +``` + +Here, `ToggleNodeFilter` is a [message](message.md) that adds or removes +(toggles) the filter applied. diff --git a/docs/en/src/general-config.md b/docs/en/src/general-config.md index 9ab1473..74a1067 100644 --- a/docs/en/src/general-config.md +++ b/docs/en/src/general-config.md @@ -61,7 +61,140 @@ initial_layout Type: string -The name of one of the defined [layouts](layouts.md) to use when xplr loads. +The name of one of the [layout](layouts.md) to use when xplr loads. +initial_mode +------------ + +Type: string + +The name of one of the [mode](modes.md) to use when xplr loads. + + +initial_sorting +--------------- + +Type: list of [Node Sorter Applicable](sorting.md#node-sorter-applicable) + +Initial group if sorters applied to the nodes list in the table. + + +table.style +----------- + +Type: [Style](style.md) + +Default style of the table. + + +table.col_spacing +----------------- + +Type: nullable integer + +Default spacing of the columns in the table. + + +table.col_widths +---------------- + +Type: nullable list of [Constraint](layouts.md#constraint) + +Width of each column in the table. + +table.header.height +---------------- + +Type: nullable integer + +Height of the table header. + + +table.header.style +--------------- + +Type: [Style](style.md) + +Style of table header. + + +table.header.cols +----------------- + +Type: List of column configuration + +Each column config contains `format` field (string) and `style` field +([Style](style.md)), that define the content and style of header. + + +table.row.height +---------------- + +Type: nullable integer + +Height of each row in the table. + + +table.row.style +--------------- + +Type: [Style](style.md) + +Style of table rows. + + +table.row.cols +----------------- + +Type: List of column configuration + +Each column config contains `format` field (string) and `style` field +([Style](style.md)). + +However, unlike [table.header.cols](#tableheadercols), the `format` field here +points to a Lua function that receives a +[special argument](https://docs.rs/xplr/latest/xplr/ui/struct.NodeUiMetadata.html) +as input and returns a string that will be displayed in the column. + +TODO: Document the argument fields here. + +xplr by default provides the following functions: + +- `xplr.fn.builtin.fmt_general_table_row_cols_0` +- `xplr.fn.builtin.fmt_general_table_row_cols_1` +- `xplr.fn.builtin.fmt_general_table_row_cols_2` +- `xplr.fn.builtin.fmt_general_table_row_cols_3` +- `xplr.fn.builtin.fmt_general_table_row_cols_4` + +You can either overwrite these functions, or create new functions in +`xplr.fn.custom` and point to them. + +Terminal colors are supported. + +Example: + +```lua +xplr.fn.custom.fmt_simple_column = function(m) + return m.prefix .. m.relative_path .. m.suffix +end + +xplr.config.general.table.header.cols = { + { format = " path" } +} + +xplr.config.general.table.row.cols = { + { format = "custom.fmt_simple_column" } +} + +xplr.config.general.table.col_widths = { + { Percentage = 100 } +} + +-- With this config, you should only see a single column displaying the +-- relative paths. +``` + +------------ + TODO: Continue documentation diff --git a/docs/en/src/sorting.md b/docs/en/src/sorting.md new file mode 100644 index 0000000..7d18000 --- /dev/null +++ b/docs/en/src/sorting.md @@ -0,0 +1,83 @@ +Sorting +======= + +xplr supports sorting paths by different properties. The sorting mechanism +works like a pipeline, which in visible in the `Sort & filter` panel. + +Example: + +``` +size↑ › [i]rel↓ › [c]dir↑ › [c]file↑ › sym↑ +``` + +This line means that the nodes visible on the table will be first sorted by +relative file size, then by case insensitive relative path, then by the +canonical (symlink resolved) type of the node, and finally by whether or not +the node is a symlink. + +The arrows denote the order. + +Each part of this pipeline is called [Node Sorter Applicable](#node-sorter-applicable). + + +Node Sorter Applicable +---------------------- + +It contains the following information: + +- [sorter](#sorter) +- [reverse](#reverse) + + +### sorter + +A sorter can be one of the following: + +- "ByRelativePath" +- "ByIRelativePath" +- "ByExtension" +- "ByIsDir" +- "ByIsFile" +- "ByIsSymlink" +- "ByIsBroken" +- "ByIsReadonly" +- "ByMimeEssence" +- "BySize" +- "ByCanonicalAbsolutePath" +- "ByICanonicalAbsolutePath" +- "ByCanonicalExtension" +- "ByCanonicalIsDir" +- "ByCanonicalIsFile" +- "ByCanonicalIsReadonly" +- "ByCanonicalMimeEssence" +- "ByCanonicalSize" +- "BySymlinkAbsolutePath" +- "ByISymlinkAbsolutePath" +- "BySymlinkExtension" +- "BySymlinkIsDir" +- "BySymlinkIsFile" +- "BySymlinkIsReadonly" +- "BySymlinkMimeEssence" +- "BySymlinkSize" + +TODO: document each + + +### reverse + +Type: boolean + +It defined the direction of the order. + + +Example +------- + +```lua +xplr.config.general.initial_sorting = { + { sorter = "ByCanonicalIsDir", reverse = true }, + { sorter = "ByIRelativePath", reverse = false }, +} +``` + +This snippet defines the initial sorting logic to be applied when xplr loads. diff --git a/docs/en/src/upgrade-guide.md b/docs/en/src/upgrade-guide.md index 8a81ec4..cf2b067 100644 --- a/docs/en/src/upgrade-guide.md +++ b/docs/en/src/upgrade-guide.md @@ -46,7 +46,7 @@ compatibility. ### Instructions -#### [v0.13.7](https://github.com/sayanarijit/xplr/releases/tag/v0.13.7) -> [v0.14.2](https://github.com/sayanarijit/xplr/releases/tag/v0.14.2) +#### [v0.13.7](https://github.com/sayanarijit/xplr/releases/tag/v0.13.7) -> [v0.14.3](https://github.com/sayanarijit/xplr/releases/tag/v0.14.3) - macOS users need to place their config file (`init.lua`) in `$HOME/.config/xplr/` or `/etc/xplr/`. @@ -55,6 +55,10 @@ compatibility. for [FIFO based file previews](https://github.com/sayanarijit/xplr/pull/229#issue-662426960). - You can disable the recover mode using `config.general.disable_recover_mode = true`. - Try running `xplr --help`. Yes, CLI has been implemented. +- Since version `v0.14.3`, `StartFifo` and `ToggleFifo` will write to the FIFO + path when called. So, there's no need to pipe the focus path explicitely. +- Since version `v0.14.3`, general config `xplr.config.start_fifo` is available + which can be set to a file path to start a fifo when xplr starts. Like this project so far? **[Please consider contributing](contribute.md)**.