feat: Add custom grouping, with 'group by function' option (#2028)

* feat: Add outline FunctionField class - does nothing yet.

* feat: Add 'group by function' code

Total credit for this goes to Jules Omlor.

I just updated it to work with the current Tasks code,
and added initial tests.

Co-Authored-By: Jules Omlor <jules@haunted.host>

* feat: Only support access to Task object in 'group by function'

This will mean there is a lot less to document.
And I will gradually expose Task facilities, and document them
as they become stable.

* test: Add more useful examples of using task status symbols

* comment: Add TODO, mainly to make formatting of code clearer

* feat: Hook up 'group by function' in Query

* spike: Experiment with calling groupByFn() directly

In preparation for machine-generating documentation.

* refactor: Flip an if and unwrap the else

* fix: Give a meaningful message for incorrect expression type

* feat: Give a meaningful message for incorrect expression type

* feat: Give a meaningful message for syntax errors

* feat: Extract evaluateExpression(), to calculate any expression on Task

* test: Generate a table of status fields for custom functions

* docs: Interim commit of docs for 'group by function'

* test: Extract helper verifyFieldDataForReferenceDocs()

* docs: Document all the supported fields for 'group by function'

* docs: Format strings in field tables as code with backticks

* docs: Document more Values for Other Task Properties

And add some TODOs

* docs: Move reference material to Reference section & add more detail

* refactor: Use early return in evaluateExpression()

* docs: Move Functions.md content to new section in Grouping.md

* docs: Work in progress on functions section in Grouping.md

* docs: Add picture of how group by function works

* fix: Remove the need to convert non-string types to strings

* fix: An empty group heading is treated as un-grouped.

* fix: An empty group heading is treated as un-grouped.

* fix: Report errors for exception, null and undefined return values

* fix: Do not escape markdown characters in function group headings

It's easier to not do that, and allow users to do it optionally,
than to do it on all fields and find that things like tags with underscores
in are broken.

* docs: Capture my current understanding of 'group by function'

* docs: Add value and type for an unpopulated task

* test: Check behaviour of of falsey values

* test: Show values of dates, and of IN_PROGRESS task

* docs: Update Task Properties.md for latest test output

* docs: Fix the type displayed for task.tags

* docs: Fix the values displayed for task.tags

* jsdoc: Document that GroupingTreeNode field must be populated

* fix: Simplify the handling of empty strings, as groups with empty names now work

* docs: Start a minimal page on expressions.

* test: Extract a variable to re-use values

* test: Prepare to convert expression test to approval tests

* test: Remove placeholder text from ApprovalTest docs

* test: Move some grouping test helpers to CustomMatchersForGrouping.ts

* refactor: Rename variable as it is no longer specific to grouping

* refactor: Move evaluateExpression() to Scripting/Expression.ts

* test: Rename FunctionFieldReference.test.ts to TaskProperties.test.ts

This is part of breaking up the 'group by function' code to more
general scripting code

* test: Move TaskProperties.test.ts to Scripting folder

* test: Add a test of expression calculation results

* test: Add own implementation of verifyAll() - based on verifyAllCombinations1()

* test: Remove [] from around a in the approved file (due to use of combinations)

* test: Move test of evaluateExpression() to Scripting/Expression.test.ts

* test: Fix misleading variable name

* docs: Update include file names for recent changes

* test,docs: Generate a markdown table of expression results, for docs.

* test,docs: Generate a block of expression results, for docs.

Escaping any pipes in table values was going to just be too much work.

Also, add some text to Expressions.md

* docs: About Scripting Details.md now links to Expressions and scripting tag

* docs: Move scripting docs to top level of docs for visibility

* docs: Start a page on Custom Grouping

* test: Rename test helper function determineExpression()

* test: Move some test helpers out to own file in tests/Scripting

* docs,test: Properly format the expression results in Expressions.md

* docs,test: Show an example of arithmetic in expressions

* docs: Move detail of 'group by function' docs to Custom Grouping.md

* docs: Remove a callout for issue that is now fixed

* test: Add example showing that ' and " can both be used

* feature: Treat group "name" null as an empty group, for user convenience.

* docs: Note that task.tags does not contain any tag that is the global filter

* test: Add variety of sample custom groups in TagsField.test.ts

These will eventually be used to add to the documentation.

* test: TagsField.test.ts now makes markdown file of custom groups.

* docs: Add sample 'custom grouping by tags' text to Grouping docs

* docs: Better formatting of custom grouping samples

* docs: Update Expressions.md for recent change in tests

* test: Move 'custom grouping by tag' documentation tests to separate folder

To avoid cluttering up the main Filter tests

* test: Extract function verifyHeadingsFromSampleGroupers()

* test: Extract function verifyHelpFromSampleGroupers()

* test: Clearer function names

* test: Clearer function names again

* test: Move two helper functions out to VerifyFunctionFieldSamples.ts

To prepare for writing more tests for other fields.

* docs: Add sample 'custom grouping by status names' text to Grouping docs

* text: Correct descriptive text for documentation

* docs: Add sample 'custom grouping by status types' text to Grouping docs

* docs: Add sample 'custom grouping by status symbols' text to Grouping docs

* docs: Add sample 'custom grouping by next status symbol' text to Grouping docs

* docs: Add sample 'custom grouping by due date' text to Grouping docs

* docs: Remove incorrect task property task.status.createdDate from docs

* refactor: Add created, done, due, scheduled and start to Task

This will allow Task References in scripting to match the
field names used in the existing search filters.

* docs,test: Add created, done, due, scheduled and start properties on task

so that the fields in scripting are consistent with those used in existing searches,.

* test: Add fake date to DueDateFieldDocs.test.ts to fix failing tests

* docs: Add sample 'custom grouping by done date' text to Grouping docs

* docs: Add sample 'custom grouping by created, scheduled and start date' text to Grouping docs

* test: Fix error that tests were using tasks without the right dates.

* feat: Add support and docs for task.happens in 'group by function'

* docs: Update Task Properties.md for the addition of task.happens

* docs: Fix the type displayed for null in Task Properties.md

* docs: Display type of Moment objects correctly

* docs: Display values of Moment objects correctly

* docs: Add a link to examples of using date properties

* test: Add samples for 'group by function task.description'

* test: Parameterize a test, to make it easier to test more properties

* test: Inline the list of custom groups

* test: Clearer names of approved files

* docs: Add samples for 'group by function task.description'

* fix: Withdraw support for task.blockLink for now

Its leading space is confusing, and including the '^' in output
causes Obsidian to think that the displayed text is itself a blocklink.
It maybe better to store the blocklink without the leading ' ^'

* test: Add test of Task.indentation

* fix: Withdraw support for task fields not already released

It's taking too long to write the documentation for them.
And adding the tests to generate the docs is showing potential
sources of confusion in some of them, like task.indentation with blockquotes.

They can be added later as new features.

* docs: Remove from docs file properties that will not be released as-is for scripting.

* docs: Work-in-progress commit of Custom Grouping.md

* test: Add some ideas for examples to TaskPropertyExamples.test.ts

* feat: Add Task.recurring - but don't yet document, as Task.recurrence is not releasable

... as it cannot return a string value, due to name-clash with existing recurrence field in Task.

* docs: Note that all task dates have time midnight currently

* docs: Remove task.priority from docs.

I think it will be more useful for task.priority to refer to the name.
Currently, it gives the number. Needs more thought.

* fix: Add Task.dateTimeFormat - should have been in an earlier commit.

* docs: Document 'group by function task.urgency'

* docs: Comment out File Properties section until precedingHeader renamed

* test: Move 'group by function task.tags' docs tests to TaskPropertyExamples.test.ts

* test: Move 'group by function task.status.type' docs tests to TaskPropertyExamples.test.ts

* test: Move 'group by function task.status.symbol' docs tests to TaskPropertyExamples.test.ts

* test: Move 'group by function task.status.nextStatusSymbol' docs tests to TaskPropertyExamples.test.ts

* test: Correct order of test names to alphabetical

* test: Move 'group by function task.status.name' docs tests to TaskPropertyExamples.test.ts

* test: Move 'group by function task.start' docs tests to TaskPropertyExamples.test.ts

* test: Move 'group by function task.scheduled' docs tests to TaskPropertyExamples.test.ts

* test: Move 'group by function task.happens' docs tests to TaskPropertyExamples.test.ts

* test: Move 'group by function task.done' docs tests to TaskPropertyExamples.test.ts

* test: Move 'group by function task.created' docs tests to TaskPropertyExamples.test.ts

* docs: Update embedded file names in Grouping.md

For recent changes in test file names.

* test: Fix failing test for TaskPropertyExamples.test.ts by fixing date

* refactor: Don't allow null to be passed in groupByFn()

* refactor: Rename groupByFn()

* jsdoc: Add minimal docs to scripting code

---------

Co-authored-by: Jules Omlor <jules@haunted.host>

docs/Introduction.md

@@ -32,6 +32,7 @@ These are the main pages and sections, that connect to all the pages here:
 >
 > ### Advanced and Detail
 >
+> - [[About Scripting|Scripting ...]]
 > - [[About Advanced|Advanced ...]]
 > - [[About Other Plugins|Other Plugins ...]]
 > - [[About Reference|Reference ...]]