feat(tags): review dev.get template tag

docs/reference__tags.md

@@ -679,11 +679,56 @@ Dumps and prettifies any JavaScript value
 ```
 <!-- tabs:end -->
 
-### `.color TODO` :id=dev-color
-TODO
 
-### `.get TODO` :id=dev-get
-TODO
+### `.get` :id=dev-get
+Retrieves values by following a specified path in the provided object. Helpful for parametrizing templates.
+
+`dev.get(path, obj? = c)`
+- `path`: a string representing the path to access the value.
+    - Can contain attribute names separated by dots `.`.
+    - It can also include `@` followed by the property name to access the property value.
+    - After `@` and the property name, it can contain `.` followed by a numeric index to access the Nth reference inside the property value.
+- `obj`: (optional) an object to retrieve the value from (default: context variable `c`)
+
+<!-- tabs:start -->
+#### ***Template***
+```
+- template:: test
+    - ``dev.get('page.name')``
+    - ``dev.get('.name', c.page)``
+    - ``dev.get('.name', c.template)``
+```
+
+#### ***Rendered***
+```
+- Test Page
+- Test Page
+- test
+```
+<!-- tabs:end -->
+
+<!-- tabs:start -->
+#### ***Template***
+```
+- template:: test
+  arg-value:: VALUE
+  refs:: [[link]] to #page
+    - ``dev.get('@arg-value', c.template)``
+    - ``dev.get('@refs', c.template)``
+    - ``dev.get('@refs.all', c.template)``
+    - ``dev.get('@refs.1', c.template)``
+```
+
+#### ***Rendered***
+```
+- VALUE
+- [[link]] to #page
+- [[link]], [[page]]
+- [[page]]
+```
+<!-- tabs:end -->
+
+?> Another example of usage is [here](https://github.com/stdword/logseq13-full-house-plugin/discussions/9#view-for-blocks)
 
 ### `.links TODO` :id=dev-links
 TODO

src/tags.ts

@@ -613,49 +613,72 @@ function color(value: string): string {
     if (!value.startsWith('#'))
         value = `#${value}`
     return value
- }
-function get(context: C, path: string): string {
+}
+function get(context: C, path: string, obj?: any): string {
     path = _asString(path)
 
     function getByPath(obj: any, parts: string[]) {
-        while (parts.length)
-            if (typeof obj == 'object') {
-                let attr = parts.shift() as string
-                if (attr === '@') {
-                    const token = parts.at(0) ?? ''
-                    const refs = obj['propsRefs'][token]
-                    if (refs !== undefined) {
-                        if (refs.length !== 0) {
-                            parts.shift()  // release token
-
-                            const nextToken = parts.shift() ?? ''
-                            if (nextToken === '')
-                                obj = refs.map((r) => `[[${r}]]`)
-                            else {
-                                const index = Math.min(Number(nextToken), refs.length - 1)
-                                obj = `[[${refs[index]}]]`
-                            }
-                            continue
-                        }
-                    }
-                    attr = 'props'
+        while (parts.length) {
+            if (typeof obj !== 'object')
+                return undefined
+
+            let attr = parts.shift() as string
+
+            if (attr === '@') {
+                if (!parts.length) {
+                    obj = obj['props']
+                    continue
+                }
+
+                let token = parts.at(0)  // @token1
+                const refs = obj['propsRefs'][token as string]
+
+                if (refs === undefined || refs.length === 0) {
+                    obj = obj['props']
+                    continue
+                }
+
+                token = parts.at(1)  // @token1.token2
+                if (token === undefined) {
+                    // fallback to props text values
+                    obj = obj['props']
+                    continue
                 }
-                obj = obj[attr]
+
+                parts.shift()  // release token1
+                parts.shift()  // release token2
+
+                let index = Number(token)
+                if (Number.isNaN(index)) {
+                    // get all refs
+                    obj = refs.map((r) => `[[${r}]]`)
+                    break
+                }
+
+                // get ref at index
+                index = Math.min(index, refs.length - 1)
+                obj = `[[${refs[index]}]]`
+
+                continue
             }
-            else return undefined
+
+            obj = obj[attr]
+        }
+
         return obj
     }
 
     path = path.replaceAll('@', '.@.')
-    const parts = path.split('.')
+    const parts = path.split('.').filter(p => p !== '')
 
-    if (parts[0] === 'c')
+    if (parts[0] === 'c' && obj === undefined)
         parts.shift()
 
     if (!parts.length)
         return ''
 
-    return getByPath(context, parts) ?? ''
+    obj = obj !== undefined ? obj : context
+    return getByPath(obj, parts) ?? ''
 }
 
 function parseLinks(context: C, text: string): string[] {