From 4a27ef03d26075d22f7403ff6e86378c4f622f62 Mon Sep 17 00:00:00 2001 From: SebastianMC <23032356+SebastianMC@users.noreply.github.com> Date: Tue, 7 Feb 2023 17:13:32 +0100 Subject: [PATCH] #50 - regexp and by-name matching support for target-folder - documentation update --- docs/manual.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 184 insertions(+), 1 deletion(-) diff --git a/docs/manual.md b/docs/manual.md index b6f1cb1..79e091b 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -70,7 +70,7 @@ For clarity: the three available prefixes `/!` and `/!!` and `/!!!` allow for fu ## Simple wildcards -Currently, the below simple wildcard syntax is supported: +Currently, the below simple wildcard syntax is supported for sorting group: ### A single digit (exactly one) @@ -248,3 +248,186 @@ sorting-spec: | /! starred: --- ``` + +## Options for target-folder: matching + +The `target-folder:` has the following variants, listed in the order of precedence: + +1. match by the **exact folder path** (the default) +2. match by the **exact folder name** +3. match by **regexp** (for experts, be careful!) +4. match by **wildcard suffix** (aka match folders subtree) + +If a folder in the vault matches more than one `target-folder:` definitions, +the above list shows the precedence, e.g. 1. has precedence over 2., 3. and 4. for example. +In other words, match by exact folder path always wins, then goes the match by folder exact name, +and so on. + +If a folder in the vault matches more than one `target-folder:` definitions of the same type, +see the detailed description below for the behavior + +### By folder path (the default) + +If no additional modifiers follow the `target-folder:`, the remaining part of the line +is treated as an exact folder path (leading and trailing spaces are ignored, +infix spaces are treated literally as part of the folder path) + +Within the same vault duplicate definitions of same path in `target-folder:` are detected +and error is raised in that case, indicating the duplicated path + +Examples of `target-folder:` with match by the exact folder path: + +- `target-folder: My Folder` + - this refers to the folder in the root of the vault and only to it +- `target-folder: Archive/My Folder` + - matches the `My Folder` sub-folder in the `Archive` folder (a sub-folder of the root) +- `target-folder: .` + - this refers to path of the folder where the sorting specification resides (the specification containing the line, + keep in mind that the sorting specification can reside in multiple locations in multiple notes) +- `target-folder: ./Some Subfolder` + - this refers to path of a sub-folder of the folder where the sorting specification resides (the specification containing the line, + keep in mind that the sorting specification can reside in multiple locations in multiple notes) + +### By folder name + +The modifier `name:` tells the `target-folder:` to match the folder name and not the full folder path + +This is an exact match of the full folder name, no partial matching + +Within the same vault duplicate definitions of same name in `target-folder: name:` are detected +and error is raised in that case, indicating the duplicated folder name in sorting specification + +Examples of `target-folder:` with match by the exact folder name: + +- `target-folder: name: My Folder` + - matches all the folders with the name `My Folder` regardless of their location within the vault + +### By regexp (expert feature) + +> WARNING!!! This is an EXPERT FEATURE. +> +> Involving and constructing the regexp-s requires at least basic knowledge about the potential pitfalls.\ +> If you introduce a heavy _regexp-backtracking_ it can **kill performance of Obsidian and even make it unresponsive**\ +> If you don't know what the _regexp-backtracking_ is, be careful when using regexp for `target-folder:` + +The modifier `regexp:` tells the `target-folder:` to involve the specified regular expressions in matching + +Additional dependent modifiers are supported for `regexp:`: +- `for-name:` + - tells the matching to be done against the folder name, not the full path +- `debug:` + - tells the regexp to report its match in the developer console, so that you can easily investigate + why the regexp matches (or why it doesn't match) as expected +- `/!:` `/!!:` `/!!!:` + - sets the priority of the regexp + +By default, the regexp is matched against the full path of the folder, unless the `for-name:` modifiers tells otherwise. + +By default, the regexp-es have no priority and are evaluated in the order of their definition.\ +If you store `sorting-spec:` configurations in notes spread all over the vault, +consider the order of `target-folder: regexp:` to be undefined and - if needed - use +explicit priority modifiers (`/!:` `/!!:` `/!!!:`) to impose the desired order of matching. + - a regexp with modifier `/!!!:` if evaluated before all other regexps, regardless of where they are configured + - if two or more regexps are stamped with `/!!!:`, they are matched in the order in which they were defined.\ + Within a single YAML section of a note the order is obvious.\ + For sorting specifications spread over many notes in the vault consider the order to be undefined. + - a regexp with modifier `/!!:` if evaluated after any `/!!!:` and before all other regexps + - the same logic as described above applies when multiple regexps have the `/!!:` stamp + - a regexp with modifier `/!:` indicates the lowest of explicitly defined priorities.\ + Such a regexp is matched after all priority-stamped regexps, before the regexps not having + any explicit priority stamp + +The escape character is \ - the standard one in regexp world. + +Examples of `target-folder:` with match by regexp: + +- `target-folder: regexp: reading` + - matches any folder which contains the word `reading` in its path or name +- `target-folder: regexp: \d?\d-\d?\d-\d\d\d\d$` + - matches any folder which ends with date-alike numerical expression, e.g.: + - `1-1-2023` + - `Archive/Monthly/12/05-12-2022` + - `Inbox/Not digested notes from 20-7-2019` +- `target-folder: regexp: for-name: I am everywhere` + - matches all folders which contain the phrase `I am everywhere` in their name, e.g.: + - `Reports/Not processed/What the I am everywhere report from Paul means?` + - `Chapters/I am everywhere` +- `target-folder: regexp: for-name: ^I am (everyw)?here$` + - matches all folders with name exactly `I am everywhere` or `I am here` +- `target-folder: regexp: for-name: debug: ^...$` + - matches all folders with name comprising exactly 3 character + - when a folder is matched, a diagnostic line is written to the console - `debug:` modifiers enables the logging +- `target-folder: regexp: debug: ^.{13,15}$` + - matches all folders with path length between 13 and 15 characters + - diagnostic line is written to the console due to `debug:` +- `target-folder: regexp: for-name: /!: ^[aA]` + - matches all folders with name starting with `a` or `A` + - the priority `/!:` modifier causes the matching to be done before all other regexps + which don't have any priority +- `target-folder: regexp: /!!!: debug: for-name: abc|def|ghi` + - matches all folders with name containing the sequence `abc` or `def` or `ghi` + - the modifier `/!!!:` imposes the highest priority of regexp matching + - `debug:` tells to report each matching folder in the console +- `target-folder: regexp: ^[^/]+/[^/]+$` + - matches all folders which are at the 2nd level of vault tree, e.g.: + - `Inbox/Priority input` + - `Archive/2021` +- `target-folder: regexp: ^[^\/]+(\/[^\/]+){2}$` + - matches all folders which are at the 3rd level of vault tree, e.g.: + - `Archive/2019/05` + - `Aaaa/Bbbb/Test test` + +### By wildcard + +In the default usage of `target-folder:` with the exact full folder path, if the path contains +the `/...` or `/*` suffix its meaning is extended to: +- match the folder and all its immediate (child) subfolders - `/...` suffix +- match the folder and all its subfolders at any level (all descendants, the entire subtree) - `/*` suffix + +For example: + +- `target-folder: /*` + - matches all folders in the vault (the root folder and all its descendants) +- `target-folder: /...` + - matches the root folder and its immediate children (aka immediate subfolders of the root) + +If the sorting specification contains duplicate wildcard-ed path in `target-folder:` +an error is raised, indicating the duplicate path + +If a folder is matched by two (or more) wildcarded paths, the one with more path segments +(the deeper one) wins. For example: +- a folder `Book/Chapters/12/a` is matched by: + - (a) `target-folder: Book/*`, and + - (b) `target-folder: Book/Chapters/*` + - In this case the (b) wins, because it contains a deeper path + +If the depth of matches specification is the same, the `/...` takes precedence over `/*` +- a folder `Book/Appendix/III` is matched by: + - (a) `target-folder: Book/Appendix/...`, and + - (b) `target-folder: Book/Appendix/*` + - In this case the (a) wins + +## Excluding folders from custom sorting + +Having the ability to wildard- and regexp-based match of `target-folder:` in some cases +you might want to exclude folder(s) from custom sorting. + +This can be done by combination of the `target-folder:` (in any of its variants) +and specification of the sort order as `sorting: standard` + +An example piece of YAML frontmatter could look like: + +```yaml +--- +sorting-spec: | + + // ... some sorting specification above + + target-folder: Reviews/Attachments + target-folder: TODOs + sorting: standard + + // ... some sorting specification below + +--- +```