Merge pull request #3581 from obsidian-tasks-group/issue_3580_nested_properties

docs: Document access to nested and object properties

Author: claremacrae

docs/Getting Started/Obsidian Properties.md

@@ -187,8 +187,7 @@ group by function \
 
 Consider a file with the following example properties (or "Frontmatter"):
 
-<!-- TODO this was copied from docs_sample_for_task_properties_reference.md - embed the content automatically in future... -->
-
+<!-- snippet: DocsSamplesForDefaults.test.DocsSamplesForDefaults_interpret_properties.approved.yaml -->
 ```yaml
 ---
 sample_checkbox_property: true
@@ -214,8 +213,14 @@ tags:
   - tag-from-file-properties
 creation date: 2024-05-25T15:17:00
 project: Secret Project
+nested_data:
+  surname: "Doe"
+  firstname: "Jane"
+  middle name: "Frances"
+object_serialization: {"nested1": "value1", "nested2": "value2"}
 ---
 ```
+<!-- endSnippet -->
 
 The following table shows how most of those properties are interpreted in Tasks queries:
 
@@ -235,6 +240,11 @@ The following table shows how most of those properties are interpreted in Tasks
 | `task.file.property('sample_link_property')` | `string` | `'[[yaml_all_property_types_populated]]'` |
 | `task.file.property('sample_link_list_property')` | `string[]` | `['[[yaml_all_property_types_populated]]', '[[yaml_all_property_types_empty]]']` |
 | `task.file.property('tags')` | `string[]` | `['#tag-from-file-properties']` |
+| `task.file.property('nested_data').surname` | `string` | `'Doe'` |
+| `task.file.property('nested_data').firstname` | `string` | `'Jane'` |
+| `task.file.property('nested_data')['middle name']` | `string` | `'Frances'` |
+| `task.file.property('object_serialization').nested1` | `string` | `'value1'` |
+| `task.file.property('object_serialization').nested2` | `string` | `'value2'` |
 
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 

docs/Scripting/Task Properties.md

@@ -229,6 +229,11 @@ These are described in full in [[Obsidian Properties]].
 | `task.file.property('sample_link_property')` | `string` | `'[[yaml_all_property_types_populated]]'` |
 | `task.file.property('sample_link_list_property')` | `string[]` | `['[[yaml_all_property_types_populated]]', '[[yaml_all_property_types_empty]]']` |
 | `task.file.property('tags')` | `string[]` | `['#tag-from-file-properties']` |
+| `task.file.property('nested_data').surname` | `string` | `'Doe'` |
+| `task.file.property('nested_data').firstname` | `string` | `'Jane'` |
+| `task.file.property('nested_data')['middle name']` | `string` | `'Frances'` |
+| `task.file.property('object_serialization').nested1` | `string` | `'value1'` |
+| `task.file.property('object_serialization').nested2` | `string` | `'value2'` |
 
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 

resources/sample_vaults/Tasks-Demo/Test Data/docs_sample_for_task_properties_reference.md

@@ -22,6 +22,11 @@ tags:
   - tag-from-file-properties
 creation date: 2024-05-25T15:17:00
 project: Secret Project
+nested_data:
+  surname: "Doe"
+  firstname: "Jane"
+  middle name: "Frances"
+object_serialization: {"nested1": "value1", "nested2": "value2"}
 ---
 
 # docs_sample_for_task_properties_reference

tests/DocumentationSamples/DefaultsDocs/DocsSamplesForDefaults.test.DocsSamplesForDefaults_interpret_properties.approved.yaml

@@ -0,0 +1,30 @@
+---
+sample_checkbox_property: true
+sample_date_property: 2024-07-21
+sample_date_and_time_property: 2024-07-21T12:37:00
+sample_list_property:
+  - Sample
+  - List
+  - Value
+sample_number_property: 246
+sample_text_property: Sample Text Value
+sample_text_multiline_property: |
+  Sample
+  Text
+  Value
+sample_link_property: "[[yaml_all_property_types_populated]]"
+sample_link_list_property:
+  - "[[yaml_all_property_types_populated]]"
+  - "[[yaml_all_property_types_empty]]"
+aliases:
+  - YAML All Property Types Populated
+tags:
+  - tag-from-file-properties
+creation date: 2024-05-25T15:17:00
+project: Secret Project
+nested_data:
+  surname: "Doe"
+  firstname: "Jane"
+  middle name: "Frances"
+object_serialization: {"nested1": "value1", "nested2": "value2"}
+---

tests/DocumentationSamples/DefaultsDocs/DocsSamplesForDefaults.test.ts

@@ -2,6 +2,7 @@ import type { Pos } from 'obsidian';
 
 import { verify, verifyAsJson } from 'approvals/lib/Providers/Jest/JestApprovals';
 import { getTasksFileFromMockData } from '../../TestingTools/MockDataHelpers';
+import docs_sample_for_task_properties_reference from '../../Obsidian/__test_data__/docs_sample_for_task_properties_reference.json';
 import query_file_defaults_all_options_null from '../../Obsidian/__test_data__/query_file_defaults_all_options_null.json';
 import query_file_defaults_all_options_true from '../../Obsidian/__test_data__/query_file_defaults_all_options_true.json';
 import query_file_defaults_short_mode from '../../Obsidian/__test_data__/query_file_defaults_short_mode.json';
@@ -32,6 +33,10 @@ describe('DocsSamplesForDefaults', () => {
         verifyWithFileExtension(extractFrontmatter(query_file_defaults_all_options_true), '.yaml');
     });
 
+    it('interpret_properties', () => {
+        verifyWithFileExtension(extractFrontmatter(docs_sample_for_task_properties_reference), '.yaml');
+    });
+
     describe('demo-short-mode', () => {
         // Load query_file_defaults_short_mode.json
         const data = query_file_defaults_short_mode;

tests/Obsidian/__test_data__/docs_sample_for_task_properties_reference.json

@@ -5,6 +5,15 @@
         "YAML All Property Types Populated"
       ],
       "creation date": "2024-05-25T15:17:00",
+      "nested_data": {
+        "firstname": "Jane",
+        "middle name": "Frances",
+        "surname": "Doe"
+      },
+      "object_serialization": {
+        "nested1": "value1",
+        "nested2": "value2"
+      },
       "project": "Secret Project",
       "sample_checkbox_property": true,
       "sample_date_and_time_property": "2024-07-21T12:37:00",
@@ -49,8 +58,8 @@
     "frontmatterPosition": {
       "end": {
         "col": 3,
-        "line": 24,
-        "offset": 614
+        "line": 29,
+        "offset": 754
       },
       "start": {
         "col": 0,
@@ -65,46 +74,46 @@
         "position": {
           "end": {
             "col": 43,
-            "line": 26,
-            "offset": 659
+            "line": 31,
+            "offset": 799
           },
           "start": {
             "col": 0,
-            "line": 26,
-            "offset": 616
+            "line": 31,
+            "offset": 756
           }
         }
       }
     ],
     "listItems": [
       {
-        "parent": -30,
+        "parent": -35,
         "position": {
           "end": {
             "col": 83,
-            "line": 30,
-            "offset": 765
+            "line": 35,
+            "offset": 905
           },
           "start": {
             "col": 0,
-            "line": 30,
-            "offset": 682
+            "line": 35,
+            "offset": 822
           }
         },
         "task": " "
       },
       {
-        "parent": -30,
+        "parent": -35,
         "position": {
           "end": {
             "col": 71,
-            "line": 31,
-            "offset": 837
+            "line": 36,
+            "offset": 977
           },
           "start": {
             "col": 0,
-            "line": 31,
-            "offset": 766
+            "line": 36,
+            "offset": 906
           }
         },
         "task": " "
@@ -115,8 +124,8 @@
         "position": {
           "end": {
             "col": 3,
-            "line": 24,
-            "offset": 614
+            "line": 29,
+            "offset": 754
           },
           "start": {
             "col": 0,
@@ -130,13 +139,13 @@
         "position": {
           "end": {
             "col": 43,
-            "line": 26,
-            "offset": 659
+            "line": 31,
+            "offset": 799
           },
           "start": {
             "col": 0,
-            "line": 26,
-            "offset": 616
+            "line": 31,
+            "offset": 756
           }
         },
         "type": "heading"
@@ -145,13 +154,13 @@
         "position": {
           "end": {
             "col": 19,
-            "line": 28,
-            "offset": 680
+            "line": 33,
+            "offset": 820
           },
           "start": {
             "col": 0,
-            "line": 28,
-            "offset": 661
+            "line": 33,
+            "offset": 801
           }
         },
         "type": "paragraph"
@@ -160,13 +169,13 @@
         "position": {
           "end": {
             "col": 71,
-            "line": 31,
-            "offset": 837
+            "line": 36,
+            "offset": 977
           },
           "start": {
             "col": 0,
-            "line": 30,
-            "offset": 682
+            "line": 35,
+            "offset": 822
           }
         },
         "type": "list"
@@ -177,13 +186,13 @@
         "position": {
           "end": {
             "col": 19,
-            "line": 28,
-            "offset": 680
+            "line": 33,
+            "offset": 820
           },
           "start": {
             "col": 0,
-            "line": 28,
-            "offset": 661
+            "line": 33,
+            "offset": 801
           }
         },
         "tag": "#tag-from-file-body"
@@ -192,13 +201,13 @@
         "position": {
           "end": {
             "col": 11,
-            "line": 30,
-            "offset": 693
+            "line": 35,
+            "offset": 833
           },
           "start": {
             "col": 6,
-            "line": 30,
-            "offset": 688
+            "line": 35,
+            "offset": 828
           }
         },
         "tag": "#task"
@@ -207,13 +216,13 @@
         "position": {
           "end": {
             "col": 83,
-            "line": 30,
-            "offset": 765
+            "line": 35,
+            "offset": 905
           },
           "start": {
             "col": 64,
-            "line": 30,
-            "offset": 746
+            "line": 35,
+            "offset": 886
           }
         },
         "tag": "#tag-from-task-line"
@@ -222,20 +231,20 @@
         "position": {
           "end": {
             "col": 11,
-            "line": 31,
-            "offset": 777
+            "line": 36,
+            "offset": 917
           },
           "start": {
             "col": 6,
-            "line": 31,
-            "offset": 772
+            "line": 36,
+            "offset": 912
           }
         },
         "tag": "#task"
       }
     ]
   },
-  "fileContents": "---\nsample_checkbox_property: true\nsample_date_property: 2024-07-21\nsample_date_and_time_property: 2024-07-21T12:37:00\nsample_list_property:\n  - Sample\n  - List\n  - Value\nsample_number_property: 246\nsample_text_property: Sample Text Value\nsample_text_multiline_property: |\n  Sample\n  Text\n  Value\nsample_link_property: \"[[yaml_all_property_types_populated]]\"\nsample_link_list_property:\n  - \"[[yaml_all_property_types_populated]]\"\n  - \"[[yaml_all_property_types_empty]]\"\naliases:\n  - YAML All Property Types Populated\ntags:\n  - tag-from-file-properties\ncreation date: 2024-05-25T15:17:00\nproject: Secret Project\n---\n\n# docs_sample_for_task_properties_reference\n\n#tag-from-file-body\n\n- [ ] #task Task in 'docs_sample_for_task_properties_reference' #tag-from-task-line\n- [ ] #task Another task in 'docs_sample_for_task_properties_reference'\n",
+  "fileContents": "---\nsample_checkbox_property: true\nsample_date_property: 2024-07-21\nsample_date_and_time_property: 2024-07-21T12:37:00\nsample_list_property:\n  - Sample\n  - List\n  - Value\nsample_number_property: 246\nsample_text_property: Sample Text Value\nsample_text_multiline_property: |\n  Sample\n  Text\n  Value\nsample_link_property: \"[[yaml_all_property_types_populated]]\"\nsample_link_list_property:\n  - \"[[yaml_all_property_types_populated]]\"\n  - \"[[yaml_all_property_types_empty]]\"\naliases:\n  - YAML All Property Types Populated\ntags:\n  - tag-from-file-properties\ncreation date: 2024-05-25T15:17:00\nproject: Secret Project\nnested_data:\n  surname: \"Doe\"\n  firstname: \"Jane\"\n  middle name: \"Frances\"\nobject_serialization: {\"nested1\": \"value1\", \"nested2\": \"value2\"}\n---\n\n# docs_sample_for_task_properties_reference\n\n#tag-from-file-body\n\n- [ ] #task Task in 'docs_sample_for_task_properties_reference' #tag-from-task-line\n- [ ] #task Another task in 'docs_sample_for_task_properties_reference'\n",
   "filePath": "Test Data/docs_sample_for_task_properties_reference.md",
   "getAllTags": [
     "#tag-from-file-properties",

tests/Scripting/TaskProperties.test.task_frontmatter_properties.approved.md

@@ -14,6 +14,11 @@
 | `task.file.property('sample_link_property')` | `string` | `'[[yaml_all_property_types_populated]]'` |
 | `task.file.property('sample_link_list_property')` | `string[]` | `['[[yaml_all_property_types_populated]]', '[[yaml_all_property_types_empty]]']` |
 | `task.file.property('tags')` | `string[]` | `['#tag-from-file-properties']` |
+| `task.file.property('nested_data').surname` | `string` | `'Doe'` |
+| `task.file.property('nested_data').firstname` | `string` | `'Jane'` |
+| `task.file.property('nested_data')['middle name']` | `string` | `'Frances'` |
+| `task.file.property('object_serialization').nested1` | `string` | `'value1'` |
+| `task.file.property('object_serialization').nested2` | `string` | `'value2'` |
 
 
 <!-- placeholder to force blank line after included text -->

tests/Scripting/TaskProperties.test.ts

@@ -188,6 +188,14 @@ describe('task', () => {
             "task.file.property('sample_link_property')",
             "task.file.property('sample_link_list_property')",
             "task.file.property('tags')",
+
+            "task.file.property('nested_data').surname",
+            "task.file.property('nested_data').firstname",
+            "task.file.property('nested_data')['middle name']",
+
+            "task.file.property('object_serialization').nested1",
+            "task.file.property('object_serialization').nested2",
+
             // 'task.file.tags', // TODO Replace
             // 'task.file.tags()', // TODO Implement
             // "task.file.tags('body')", // TODO Implement