#23 feature request sorting notes with metadata (#26)

* #23 - support for sorting by metadata

- added support for grouping items by the presence of specified metadata
  - new keyword `with-metadata:` introduced for that purpose in lexer
  - if metadata field name is omitted, the default `sort-index-value` is used
- added support for sorting items by notes and folders metadata
  - new keyword 'by-metadata:' introduced for that purpose
  - if metadata field name is omitted, the default `sort-index-value` is used (or metadata name inheritance is used)
- unit tests of sorting spec processor extended accordingly
- documentation and code example in README.md 
- extended to also support true alphabetical on metadata fields
- release unnecessary references after sorting completed

Author: SebastianMC

README.md

@@ -7,6 +7,7 @@ Take full control of the order of your notes and folders:
 - support for fully manual order
   - list notes and folders names explicitly, or use prefixes or suffixes only
   - wildcard names matching supported
+- group and sort notes and folders by notes custom metadata
 - support for automatic sorting by standard and non-standard rules
 - mixing manual and automatic ordering also supported
 - order by compound numbers in prefix, in suffix (e.g date in suffix) or inbetween 
@@ -15,7 +16,7 @@ Take full control of the order of your notes and folders:
   - different sorting rules per group even inside the same folder
 - simple to use yet versatile configuration options
 - order configuration stored directly in your note(s) front matter
-  - use a dedicated key in YAML
+  - use a dedicated `sorting-spec:` key in YAML
 - folders not set up for the custom order remain on the standard Obsidian sorting
 - support for imposing inheritance of order specifications with flexible exclusion and overriding logic
 
@@ -35,6 +36,7 @@ Take full control of the order of your notes and folders:
   - [Example 11: Sample book structure with compound Roman number suffixes](#example-11-sample-book-structure-with-compound-roman-number-suffixes)
   - [Example 12: Apply same sorting to all folders in the vault](#example-12-apply-same-sorting-to-all-folders-in-the-vault)
   - [Example 13: Sorting rules inheritance by subfolders](#example-13-sorting-rules-inheritance-by-subfolders)
+  - [Example 14: Grouping and sorting by metadata value](#example-14-grouping-and-sorting-by-metadata-value)
 - [Alphabetical, Natural and True Alphabetical sorting orders](#alphabetical-natural-and-true-alphabetical-sorting-orders)
 - [Location of sorting specification YAML entry](#location-of-sorting-specification-yaml-entry) 
 - [Ribbon icon](#ribbon-icon)
@@ -412,6 +414,86 @@ sorting-spec: |
 ---
 ```
 
+### Example 14: Grouping and sorting by metadata value
+
+Notes can contain metadata, let me use the example inspired by the [Feature Request #23](https://github.com/SebastianMC/obsidian-custom-sort/issues/23).
+Namely, someone can create notes when reading a book and use the `Pages` metadata field. In that field s/he enters page(s) number(s) of the book, for reference.
+
+For example:
+
+```yaml
+---
+Pages: 6
+...
+---
+```
+
+or
+
+```yaml
+---
+Pages: 7,8
+...
+---
+```
+
+or 
+
+```yaml
+---
+Pages: 12-15
+...
+---
+```
+
+Using this plugin you can sort notes by the value of the specific metadata, for example:
+
+```yaml
+---
+sorting-spec: |
+    target-folder: Remarks from 'The Little Prince' book
+    < a-z by-metadata: Pages
+---
+```
+
+In that approach, the notes containing the metadata `Pages` will go first, sorted alphabetically by the value of that metadata.
+The remaining notes (not having the metadata) will go below, sorted alphabetically by default. 
+
+In the above example the syntax `by-metadata: Pages` was used to tell the plugin about the metadata field name for sorting.
+The specified sorting `< a-z` is obviously alphabetical, and in this specific context it tells to sort by the value of the specified metadata (and not by the note or folder name).
+
+In a more advanced fine-tuned approach you can explicitly group notes having some metadata and sort by that (or other) metadata:
+
+```yaml
+---
+sorting-spec: |
+    target-folder: Remarks from 'The Little Prince' book
+    with-metadata: Pages
+     < a-z by-metadata: Pages
+    ...
+     > modified
+---
+```
+
+In the above example the syntax `with-metadata: Pages` was used to tell the plugin about the metadata field name for grouping.
+The specified sorting `< a-z` is obviously alphabetical, and in this specific context it tells to sort by the value of the specified metadata (and not by the note or folder name).
+Then the remaining notes (not having the `Pages` metadata) are sorted by modification date descending.
+
+> NOTE
+> 
+> The grouping and sorting by metadata is not refreshed automatically after change of the metadata in note(s) to avoid impact on Obsidian performance.
+> After editing of metadata of some note(s) you have to explicitly click the plugin ribbon button to refresh the sorting. Or issue the command `sort on`. Or close and reopen the vault. Or restart Obsidian.
+> This behavior is intentionally different from other grouping and sorting rules, which stay active and up-to-date once enabled.
+
+> NOTE
+> 
+> For folders, metadata of their 'folder note' is scanned (if present)
+ 
+> NOTE
+> 
+> The `with-metadata:` keyword can be used with other specifiers like `/:files with-metadata: Pages` or `/folders with-metadata: Pages`
+> If the metadata name is omitted, the default `sort-index-value` metadata name is assumed.
+
 ## Alphabetical, Natural and True Alphabetical sorting orders
 
 The 'A-Z' sorting (visible in Obsidian UI of file explorer) at some point before the 1.0.0 release of Obsidian actually became the so-called 'natural' sort order.

src/custom-sort/custom-sort-types.ts

@@ -1,10 +1,13 @@
+import {MetadataCache, Plugin} from "obsidian";
+
 export enum CustomSortGroupType {
 	Outsiders, // Not belonging to any of other groups
 	MatchAll, // like a wildard *, used in connection with foldersOnly or filesOnly. The difference between the MatchAll and Outsiders is
 	ExactName,                           // ... that MatchAll captures the item (folder, note) and prevents further matching against other rules
 	ExactPrefix,						  // ... while the Outsiders captures items which didn't match any of other defined groups
 	ExactSuffix,
 	ExactHeadAndTail, // Like W...n or Un...ed, which is shorter variant of typing the entire title
+	HasMetadataField  // Notes (or folder's notes) containing a specific metadata field
 }
 
 export enum CustomSortOrder {
@@ -20,13 +23,18 @@ export enum CustomSortOrder {
 	byCreatedTimeAdvanced,
 	byCreatedTimeReverse,
 	byCreatedTimeReverseAdvanced,
+	byMetadataFieldAlphabetical,
+	byMetadataFieldTrueAlphabetical,
+	byMetadataFieldAlphabeticalReverse,
+	byMetadataFieldTrueAlphabeticalReverse,
 	standardObsidian,  // Let the folder sorting be in hands of Obsidian, whatever user selected in the UI
 	default = alphabetical
 }
 
 export interface RecognizedOrderValue {
 	order: CustomSortOrder
 	secondaryOrder?: CustomSortOrder
+	applyToMetadataField?: string
 }
 
 export type NormalizerFn = (s: string) => string | null
@@ -43,18 +51,27 @@ export interface CustomSortGroup {
 	exactPrefix?: string
 	exactSuffix?: string
 	order?: CustomSortOrder
+	byMetadataField?: string     // for 'by-metadata:' if the order is by metadata alphabetical or reverse
 	secondaryOrder?: CustomSortOrder
 	filesOnly?: boolean
 	matchFilenameWithExt?: boolean
-	foldersOnly?: boolean,
+	foldersOnly?: boolean
+	withMetadataFieldName?: string // for 'with-metadata:'
 }
 
 export interface CustomSortSpec {
 	targetFoldersPaths: Array<string>   // For root use '/'
 	defaultOrder?: CustomSortOrder
+	byMetadataField?: string            // for 'by-metadata:' if the defaultOrder is by metadata alphabetical or reverse
 	groups: Array<CustomSortGroup>
 	outsidersGroupIdx?: number
 	outsidersFilesGroupIdx?: number
 	outsidersFoldersGroupIdx?: number
 	itemsToHide?: Set<string>
+	plugin?: Plugin                     // to hand over the access to App instance to the sorting engine
+
+		// For internal transient use
+	_mCache?: MetadataCache
 }
+
+export const DEFAULT_METADATA_FIELD_FOR_SORTING: string = 'sort-index-value'