[
{
"path": ".editorconfig",
"content": "root = true\n\n# Unix-style newlines with a newline ending every file\n[*]\nend_of_line = lf\ninsert_final_newline = true\ntrim_trailing_whitespace = true\n\n# Matches multiple files with brace expansion notation\n# Set default charset\n[*.{ts,js}]\ncharset = utf-8\nindent_style = space\nindent_size = 4"
},
{
"path": ".github/FUNDING.yml",
"content": "github: [\"blacksmithgu\"]\n"
},
{
"path": ".github/ISSUE_TEMPLATE/bug_report.yml",
"content": "name: Bug Report (desktop)\ndescription: \"File a bug report for Dataview on desktop Obsidian\"\ntitle: \"Bug report\"\nlabels: [\"bug\", \"needs-investigation\"]\nbody:\n - type: markdown\n attributes:\n value: |\n Thanks for taking the time to fill out this bug report!\n - type: textarea\n id: what-happened\n attributes:\n label: What happened?\n description: Also tell us, what did you expect to happen?\n placeholder: Tell us what you see!\n validations:\n required: true\n - type: textarea\n id: dql\n attributes:\n label: DQL\n description: If applicable, provide the query where the bug occurred\n placeholder: |\n ```dataview\n LIST FROM #example\n ```\n - type: textarea\n id: js\n attributes:\n label: JS\n description: If applicable, provide the javascript where the bug occurred\n render: js\n - type: input \n id: version\n attributes:\n label: Dataview Version\n description: What version of Dataview are you running?\n placeholder: 0.4.20\n validations:\n required: true\n - type: input \n id: obsidian-version \n attributes:\n label: Obsidian Version\n placeholder: 0.12.19\n validations:\n required: true\n - type: dropdown\n id: os\n attributes:\n label: OS\n options:\n - Windows\n - MacOS\n - Linux\n validations:\n required: true\n \n"
},
{
"path": ".github/ISSUE_TEMPLATE/bug_report_mobile.yml",
"content": "name: Bug Report (mobile)\ndescription: \"File a bug report for Dataview on mobile Obsidian\"\ntitle: \"Bug report\"\nlabels: [\"bug\", \"needs-investigation\", \"mobile\"]\nbody:\n - type: markdown\n attributes:\n value: |\n Thanks for taking the time to fill out this bug report!\n - type: textarea\n id: what-happened\n attributes:\n label: What happened?\n description: Also tell us, what did you expect to happen?\n placeholder: Tell us what you see!\n validations:\n required: true\n - type: textarea\n id: dql\n attributes:\n label: DQL\n description: If applicable, provide the query where the bug occurred\n placeholder: |\n ```dataview\n LIST FROM #example\n ```\n - type: textarea\n id: js\n attributes:\n label: JS\n description: If applicable, provide the javascript where the bug occurred\n render: js\n - type: input \n id: version\n attributes:\n label: Dataview Version\n description: What version of Dataview are you running?\n placeholder: 0.4.20\n validations:\n required: true\n - type: input \n id: obsidian-version \n attributes:\n label: Obsidian Version\n placeholder: 0.12.19\n validations:\n required: true\n - type: input\n id: device\n attributes:\n label: Device\n description: What device are you running Obsidian on? Please provide the full model (version, year, etc.)\n placeholder: iPhone 6\n validations:\n required: true\n - type: input\n id: os\n attributes:\n label: OS\n description: What OS are you running Obsidian on? Please provide the full OS version.\n placeholder: iOS 8.1\n validations:\n required: true\n \n"
},
{
"path": ".github/ISSUE_TEMPLATE/config.yml",
"content": "blank_issues_enabled: false\ncontact_links:\n - name: Dataview Discussions\n url: https://github.com/blacksmithgu/obsidian-dataview/discussions\n about: Please ask and answer questions here.\n - name: Obsidian Discord\n url: https://obsidian.md/community\n about: \"Check out the #dataview channel under the Plugins section.\"\n - name: Dataview Snippet Showcase\n url: https://forum.obsidian.md/t/dataview-plugin-snippet-showcase\n about: Show off your Dataview snippets here!\n - name: DataviewJS Snippet Showcase\n url: https://forum.obsidian.md/t/dataviewjs-snippet-showcase\n about: Show off your DataviewJS snippets here!\n"
},
{
"path": ".github/ISSUE_TEMPLATE/documentation.md",
"content": "---\nname: Documentation\nabout: Suggest improvements to documentation\ntitle: ''\nlabels: documentation\n\n---\n\n**Please provide a link to the documentation page and section**\n\n**Describe the problem**\nA clear and concise description of what is unclear about the documentation\n\n**Describe the solution you'd like**\nA clear and concise description of what you want to happen. Feel free to suggest wording, full sentences, etc.\n\n**Additional context**\nAdd any other context about the problem here.\n"
},
{
"path": ".github/ISSUE_TEMPLATE/feature_request.md",
"content": "---\nname: Feature request\nabout: Suggest an idea for this project\ntitle: ''\nlabels: feature-request\n\n---\n\n[//]: # (Note: If you are unsure about or have questions related to your feature request prefer making a discussion first. After we understand what you are looking for we can easily create an issue to track the solution and progress)\n\n**Is your feature request related to a problem? Please describe.**\nA clear and concise description of what the problem is. Ex. I'm always frustrated when [...]\n\n**Describe the solution you'd like**\nA clear and concise description of what you want to happen.\n\n**Describe alternatives you've considered**\nA clear and concise description of any alternative solutions or features you've considered.\n\n**Additional context**\nAdd any other context or screenshots about the feature request here.\n"
},
{
"path": ".github/workflows/documentation.yml",
"content": "name: docs\non:\n release:\n types:\n - published\n workflow_dispatch:\njobs:\n deploy:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-python@v4\n with:\n python-version: 3.x\n - run: |\n pip install mkdocs-material mkdocs-redirects\n cd docs\n mkdocs gh-deploy --force\n"
},
{
"path": ".github/workflows/test.yml",
"content": "name: Build and test project\non:\n push:\n branches: [ master ]\n pull_request:\n branches: [ master ]\n\njobs:\n format:\n runs-on: ubuntu-latest\n name: Check code formatting\n steps:\n - uses: actions/checkout@v3\n - name: Setup node\n uses: actions/setup-node@v3\n with:\n node-version: 16\n - run: npm install\n - run: npm run check-format\n build:\n runs-on: ubuntu-latest\n name: Build project\n steps:\n - uses: actions/checkout@v3\n - name: Setup node\n uses: actions/setup-node@v3\n with:\n node-version: 16\n - run: npm install\n - run: npm run build\n test:\n runs-on: ubuntu-latest\n name: Test project\n steps:\n - uses: actions/checkout@v3\n - name: Setup node\n uses: actions/setup-node@v3\n with:\n node-version: 16\n - run: npm install\n - run: npm run test\n"
},
{
"path": ".gitignore",
"content": "# Intellij\n*.iml\n.idea\n\n# VSCode\n.vscode\n.history/\n\n# npm\nnode_modules\n\n# build\nbuild/\n\n# Ignore .obsidian\n# No one will commit these files, they just spam 'git status'\ntest-vault/.obsidian/*\n# Tells obsidian what plugins are enabled\n!test-vault/.obsidian/community-plugins.json\n# This plugin should still be tracked by git.\n# It might need updated at some point\n!test-vault/.obsidian/hot-reload-master/*\n\n# Don't track this folder. For random things to try.\n# If its import to test though, add it somewhere where other\n# people can test it too.\ntest-vault/untracked/*\n!test-vault/untracked/README.md\n\nlib\nyarn.lock\n"
},
{
"path": ".prettierrc.json",
"content": "{\n \"tabWidth\": 4,\n \"semi\": true,\n \"embeddedLanguageFormatting\": \"off\",\n \"parser\": \"typescript\",\n \"printWidth\": 120,\n \"arrowParens\": \"avoid\"\n}\n"
},
{
"path": "CHANGELOG.md",
"content": "# 0.5.70 (Beta)\n\nStill attempting to fix #2557, github is acting up.\n\n\n---\n\n# 0.5.69 (Beta)\n\nAttempting to fix #2557, but uncertain to any side effects.\n\n\n---\n\n# 0.5.68\n\n- Many fixes to the documentation\n- #2318 & co: Various fixes related to _live preview_ rendering of lists\n- New/documented functions for `unique()`, `display()`, `firstvalue()`\n- Added DOM information related to standalone inline fields\n\nThis is the first release done by @holroy, so thanks to him for further developing of _Dataview_. Thank you also to all the people having contributed through PRs and issues.\n\n---\n\n# 0.5.67\n\nIncludes several documentation fixes and several community-contributed bug fixes.\n\n- @reply2za: Fixed inline rendering in the reading view.\n- @carlesalbasboix: Adds sum(), avg(), min(), and max() to data arrays.\n- @mnaoumov: Adds code mirror configuration which code highlights dataviewjs!\n\n---\n\n# 0.5.66\n\nBugfix for version comparisons to fix some other plugins having broken interactions with Dataview.\n\n---\n\n# 0.5.65\n\nA maintenance update which fixes some issues with rendering embeds in Dataviews and adds a few new functions.\n\n- Adds the `hash()` function for generating consistent uniformly-distributed values given arbitrary inputs. Primarily useful for creating \"random\" views which remain consistent across page refreshes. Thanks to @holroy.\n- Adds the `slice()` function for slicing arrays, similar to Javascript's `Array.slice`. Thanks to @holroy.\n- Fixes several issues with rendering embeds inside dataviews. Thanks to @GottZ.\n- Several documentation improvements around tasks - thanks to @holroy and @RaviOnline.\n\n---\n\n# 0.5.64\n\nMore bug fixes for inline field rendering.\n\n\n---\n\n# 0.5.63\n\n- More bugfixes from @RyotaUshio for rendering Markdown paragraphs and other blocks in DataviewJS.\n\n---\n\n# 0.5.62\n\nSeveral more inline field fixes from @RyotaUshio, including more configuration options, fixing inline fields being rendered inside codeblocks, and more. Thanks!\n\n---\n\n# 0.5.61\n\n- @RyotaUshio: Fix several bugs related to the new inline field rendering, including source mode and fixing date formatting.\n\n---\n\n# 0.5.60\n\n- @RyotaUshio: Add explicit rendering of inline fields in live preview. They are much more visually distinct now!\n- @MarioRicalde: Adds `PluginApi#evaluateInline(expression, path)` to the plugin API, which evaluate expressions as if you were on the given page.\n\n---\n\n# 0.5.59\n\n- Fix an issue with the plugin failing to run on iOS due to an esoteric regex issue.\n\n---\n\n# 0.5.58\n\n- Negative durations will now be properly rendered.\n\n---\n\n# 0.5.57\n\nMaintenance patch which bumps many internal dependency versions and which includes approximately ~20 community-contributed PRs which add some new functions, fix some Dataview interactions with properties, and more!\n\n---\n\n# Unreleased\n\n- DQL: Adds new `durationformat(duration, string)` function.\n- DQL: New math rounding functions, `trunc(number)`, `floor(number)`, `ceil(number)`.\n\n# 0.5.56\n\n- Includes some performance fixes on recent versions of Obsidian 1.3+ due to some API changes. Thanks @kometenstaub.\n- Documentation cleanups and improvements by @mocsa, @protofarer, @seanlzx, and @somidad.\n- Adds the new `flat(array)` method for flattening nested arrays, as well as parsing dates using arbitrary formats using\n `date(text, \"format\")`. Thanks @holroy!\n\n---\n\n# 0.5.55\n\n- Durations are now internationalized using luxon's new internationalization support.\n- Dataviews should now properly render inside Canvas and some other contexts. Thanks @GamerGirlandCo!\n\n---\n\n# 0.5.54\n\n- Regular list items are now also clickable in task views, not just task lines! Thanks to @LilaRest.\n\n---\n\n# 0.5.53\n\n- Fix some documentation issues causing docs to not be updated.\n\n---\n\n# 0.5.52\n\nSubstantial documentation improvements thanks to @s-blu and @AB1908!\n\n- For people concerned about dataviewjs code execution from copy-pasting, @eyuelt has made it possible to change the\n dataviewjs codeblock prefix.\n- @sohanglal has added some documentation for `task.visual` for changing the visual text of a task.\n- @Chouffy and @Daryl-Horton have fixed some bad documentation links!\n- @vrtmrz swapped the regex used for parsing tags to better match Obsidian's own parser.\n- @alexfertel has added `regextest`, which allows for matching parts of a string instead of the whole thing.\n- @iamrecursion has added more metadata to file links, so they now include section metadata. This may cause some slight\n visual changes in link views.\n\n---\n\n# 0.5.51 (Beta)\n\n- Allow disabling regular Dataview inline queries via configuration option.\n\n---\n\n# 0.5.50 (Beta)\n\n- Expose dataview EXPRESSION and QUERY parsing to the dataview npm plugin, so others can parse dataview ASTs.\n- Fix documentation issue with `join`.\n\n---\n\n# 0.5.49 (Beta)\n\n- Add the `average` function to compute averages of lists (`average([list of things])`).\n- Added documentation for `average`, `min`, `max`, `minby`, and `maxby` functions.\n- Fixed the broken `nonnull` function and documented it.\n\n---\n\n# 0.5.48 (Beta)\n\nWe're back to more regular beta releases while I trial out new functionality!\n\n- Fixed broken list behavior for `dv.markdownTaskList`.\n- @GamerGirlandCo: Better handling of block IDs when checking off tasks!\n- @s-blu and @AB1908: Lots of big documentation upgrades! Nice!\n- @leoccyao: More block ID task checking fixes. Should work after this one.\n- Add expression/query parsing to the dataview NPM package.\n- @charleshan: Fix a missing header level in the dataview `dv.header` example.\n\n---\n\n# 0.5.47\n\nImproves `date + duration` behavior when either the date or duration are null.\n\n---\n\n# 0.5.46\n\n- Fix #1412: Fix bad `file.cday` and `file.ctime` comparisons due to wrong timezone being set. Ugh.\n\n---\n\n# 0.5.45\n\n- #1400: Properly use the group by field for the group name.\n- Fix bad table highlighting in some themes.\n\n---\n\n# 0.5.44\n\n- #1404: Fixed dates in non-local timezones parsing incorrectly.\n- Fixed some build non-determinism issues.\n- Swapped to pull requests for adding new functionality, and added some more internal tests.\n\n---\n\n# 0.5.43\n\n- Fix #1366: Better handling of calendar emoji (used as due dates in tasks).\n\n---\n\n# 0.5.42\n\nIt's been over a month since the last release! Anyway, this release bundles several nice user-contributed features:\n\n- @AB1908: Tag queries are now case insensitive.\n- @AB1908: Shift-clicking a link/task to open in a new tab now works properly on Mac.\n- @AB1908: Numerous documentation fixes for clarity and more examples.\n- @AnnaKornfeldSimpson: Additional emoji shorthands for more task fields (finished, due).\n- @ooker777: Documentation improvements for some DataviewJS functions, and the ability to use inline emoji for the\n completion tracking feature.\n- @mt-krainski: Custom date formats for task completions.\n- @gentlegiantJGC: Better support for nested inline fields (i.e., less crashy).\n\n---\n\n# 0.5.41\n\n- Fix a bad regex doing escaping in markdown tables.\n- Improve async documentation.\n\n---\n\n# 0.5.40\n\nAdds some more documentation about the new markdown functionality.\n\n---\n\n# 0.5.39\n\n- Fixed an issue where checking a task in a task view would check the wrong box visually.\n- Added experimental plugin APIs for querying dataview directly as markdown, and converting dataview results to properly\n formatted markdown.\n\n---\n\n# 0.5.38\n\n- Some minor documentation improvements.\n- Fix an issue with inline fields rendering out of order. That was a weird bug.\n\n---\n\n# 0.5.37\n\nFixes inline field rendering to once again work for highlighting/links, as well as some other rendering quirks with\ninline queries in codeblocks.\n\n---\n\n# 0.5.36\n\n- Fix a bug when checking if an element is an HTMLElement.\n- Properly include the nice improvements to the file count in tables and lists.\n\n---\n\n# 0.5.35\n\n- Fix #1196, #1176: Re-enable HTML values. This was never a featured I advertised since it was just for some internal\n hackery, but it appears people just discovered it in DataviewJS queries.\n- Improved initial time to popular queries that use `file.starred`.\n\n---\n\n# 0.5.34\n\n- Fix #1174: Fix indexing with a variable.\n- Fix an issue with the experimental calendar view.\n\n---\n\n# 0.5.33\n\n- Fix a bug with inline views that was introduced in 0.5.32.\n\n---\n\n# 0.5.32\n\nThe Dataview API has been noticeably revamped - there are now approximately twice as many functions available on the\nplugin API as there were before, and some additional utilities have been added to both the plugin and inline API. I\nwill be finishing up the associated new \"extension\" functionality shortly, which will allow:\n\n1. For custom Dataview + DataviewJS functions to be added via plugins.\n2. For custom renderable objects (progress bars, embedded task lists, embedded tables) to be added to any Dataview view via plugins.\n3. For plugins to provide alternative behavior for some dataview functionality (such as integrating task plugins with\n the dataview task query).\n \nAs part of the API revamp, it is now possible to programmatically execute Dataview and DataviewJS queries - either for\nusing the existing Dataview query language in your own plugin, or for embedding dataview. The Dataview npm library also\nnow exposes many useful internal Dataview types, including the AST structure for all dataview queries.\n\nI am hoping that cleaning up the Dataview API and making it much more extensible will allow for Dataview [to](to) integrate\nmuch better with existing plugins, and to provide the full power of the in-memory index for plugins. I have been very\ncarefully watching index performance in recent weeks to ensure smooth frontend performance for anyone using the API\n(with a goal of <10ms for most queries).\n\n---\n\n# 0.5.31\n\nTasks now have an `outlinks` list field which includes all links in the task; this can be used for finding tasks with\nlinks in them.\n\n---\n\n# 0.5.30\n\n- Added the `typeof(any)` function in Dataview, which obtains the type of any value for comparison:\n```javascript\ntypeof(\"text\") = \"string\"\ntypeof(1) = \"number\"\ntypeof([1, 2, 3]) = \"array\"\n```\n\n- Added the modulo operator (`%`) for doing integer division remainder. I.e., `14 % 2 = 0` and `14 % 3 = 2`.\n- Fixed some minor spacing issues with lists in tables.\n\n---\n\n# 0.5.29\n\nFix another subtle incompatibility between 0.4.26 and 0.5.29 - if you frequently used empty inline fields (like\n`Key::` with no value), the 0.5+ behavior is now the same as 0.4 behavior and will map such fields to null instead of an\nempty string.\n\nThis may fix a broad variety of \"subtly wrong\" queries that you may have seen after the upgrade.\n\n---\n\n# 0.5.28\n\n- Fix a bug with some more string concatenations and null handling.\n\n---\n\n# 0.5.27\n\nMore performance + correctness bugfixes.\n\n- The parser has been made a little more robust to prevent major indexing issues (or at least recover from them\n quickly).\n- Several new strange tag variants are now supported.\n- Markdown links are now properly indexed again.\n\nSome DataviewJS performance issues should be resolved now, especially for external plugins using Dataview. This fix\ndoes involve a slight API break w.r.t. what types are wrapped into Dataview Arrays (which provide functions like\n`.where()`). Generally, only Dataview-provided implicits are wrapped in data arrays now; frontmatter and inline fields\nare always now regular JS arrays - use `dv.array()` to explicitly make a data array if you want the advanced querying.\n\n---\n\n# 0.5.26\n\nMore small bugfixes:\n\n- Fix a few small link rendering issues.\n- Tag extraction from tasks now handles punctuation properly.\n- Upgrade luxon (which is embedded in DataviewJS) to 2.4.0.\n\n---\n\n# 0.5.25\n\n- Fix #1147: Fix there being a `#null` tag for files with an empty `tag` or `tags` frontmatter.\n\n---\n\n# 0.5.24\n\nSeveral bugfixes:\n\n- Nulls are now sorted first rather than last; it's generally good practice to explicitly check for nulls in your\n queries to avoid strange behavior.\n- Dataview now properly parses space-delimited tags (like `tags: abc def ghi`).\n- Dataview now supports dropping the entire file cache in case of bugs.\n\n---\n\n# 0.5.23\n\n- Fix #1140: Force API objects to be arrays if they are iterables.\n\n---\n\n# 0.5.22\n\n- Fix #1135: Use 'x' instead of 'X' for checkboxes.\n\n---\n\n# 0.5.21\n\nA long-overdue swap from the beta branch to the stable branch. The beta branch should not include any (intended) breaking\nchanges, and has some nice performance improvements that come along with it! Here are the major changes:\n\n- Most views now use React and no longer flicker when updating; this is not the case yet for DataviewJS, which will be\n getting equivalent treatment in the future.\n- Dataview now caches metadata, so Dataview loads are very fast after the first time you open your vault. Dataview still\n needs to visit every file when you update the plugin version, so that should be the only times you experience slower\n load times.\n- A brand new task view backend and query which allows you to filter per-task, rather than per-page! Check the\n documentation for details, but this broadly means `WHERE` statements now use task properties instead of page\n properties.\n- Some additional metadata is now available for use - `file.starred`, `file.lists`, and more metadata in\n `file.tasks`.\n\nThere have been some moderate documentation touch-ups to keep things up to date; I'm still working on a walkthrough for\ncommon Dataview use cases. This review also includes about ~30-40 bugfixes; some new bugs may arise due to internal\nchanges, so please flag them if you encounter them.\n\n---\n\n# 0.5.20 (Beta)\n\nSlight fix to hopefully improve some strange reported cases of bad indexing at startup.\n\n---\n\n# 0.5.19 (Beta)\n\nDataview now uses IndexedDB to cache file metadata, reducing startup time to virtually nothing if you've opened the\nvault before; if you have a small vault (<1000 notes), you may notice a slight improvement, but large vaults and mobile\ndevices will notice a very significant performance improvement to \"first valid paint\". Some other performance parameters\nhave been tuned to hopefully make the default experience better.\n\nA few small bugs related to rendering have also been squashed, including an issue with images being scaled wrongly.\n\n---\n\n# 0.5.18 (Beta)\n\n- Tasks in task views now support alternative task status characters like '!' and '/'; thanks @ebullient.\n- A few documentation nit fixes.\n- Added `DataArray#sortInPlace` for a more efficient mutable sort for niche use cases.\n\n---\n\n# 0.5.17 (Beta)\n\n- Improved behavior when clicking on tasks in the task view; will now properly scroll to the relevant line in long\n files!\n- Fixed a bug with incorrect counts being displayed in task views.\n- Added `tags` as a field available on task items, so you can now do things like `TASK WHERE contains(tags, \"#tag\")`.\n\n---\n\n# 0.5.16 (Beta)\n\nDataview now tracks initialization and will report when all files have been indexed in the console; you can\nprogrammatically see this via `dataview:index-ready`, or by checking `api.index.initialized`.\n\n---\n\n# 0.5.15 (Beta)\n\n- Add hover highlights to tables to make seeing rows a little easier.\n- Tables and task lists now include counts of the number of results in the headers.\n- Further improved task selection in the task view.\n\n---\n\n# 0.5.14 (Beta)\n\n- Fix task highlighting when not grouping.\n- Remove some spurious console logging.\n- Slightly improve task highlighting behavior when clicking on a task.\n\n---\n\n# 0.5.13 (Beta)\n\nSeveral smaller bugfixes!\n\n- Fix #997: Use the group by field name in the table name.\n- Prevent tons of errors if you incorrectly set the inline query prefix.\n\n---\n\n# 0.5.12 (Beta)\n\nImprove error messages for queries somewhat and get rid of some ugly output.\n\n---\n\n# 0.5.11 (Beta)\n\nAdd detection of tasks inside of block quotes, as well as correctly implement automatic checking and unchecking of these\ntasks.\n\n---\n\n# 0.5.10 (Beta)\n\nAdds the `Dataview: Force Refresh Views` Command (accessible via the Ctrl+P command view) to force current views to\nrefresh immediately.\n\n---\n\n# 0.5.9 (Beta)\n\nAnother fix for due-date related emoji in tasks. I hate emoji.\n\n---\n\n# 0.5.8 (Beta)\n\nFix some issues with infinite loops of tasks due to bad Obsidian metadata (potentially due to being out of date?).\n\n---\n\n# 0.5.7 (Beta)\n\nFix issues with parsing '🗓️2021-08-29' due-date annotations on tasks, as well as an issue with properly extracting\ndue/completed/completed times for use in queries.\n\n---\n\n# 0.5.6 (Beta)\n\nProper release of 0.5.5 plus one additional small improvement:\n\n- Add `duration * number` and `duration / number` operations for manipulation durations numerically.\n\n---\n\n# 0.5.5 (Beta)\n\nMore small features:\n\n- Fix issues with task sorting not doing anything. Sort away!\n- Table headers can now be arbitrary markdown. So you can put things like links in your headers: `TABLE (1 + 2) AS\n \"[[File]]\".\n- You can now specify the size of an image embed by providing WxH in it's display property: `![[image.png|50x50]]`.\n\n---\n\n# 0.5.4 (Beta)\n\nImproved image rendering for some link types, and adds the `embed(link)` and `embed(link, false)` options to convert\nlinks to/from their embedded equivalents.\n\n---\n\n# 0.5.3 (Beta)\n\nIterative beta which adds a few nice QoL features and fixes some more bugs:\n\n- Internally swapped to a React-based renderer; this should not have a noticeable perf or usability impact, but makes it\n easier for me to implement complex table/list behaviors.\n- Naming your fields with `AS \"Name\"` is now optional; Dataview will infer the name from the expression automatically.\n For example, `TABLE 8 + 4, 3 + 6 FROM ...` is now a valid table expression, and the columns will be named `8 + 4` and\n `3 + 6` respectively.\n- Some issues with array and object rendering were corrected.\n- Error messages on empty dataview results were improved and now show up for all views.\n\nInline images are now rendered correctly in Dataview tables and lists - no more hacky `app://local/` shenanigans!\n\n---\n\n# 0.5.2 (Beta)\n\n- Fix #971: Objects now work properly inside DataviewQL evaluation.\n\n---\n\n# 0.5.1 (Beta)\n\n- Temporarily revert the new task metadata behavior: inline fields in sublists of tasks are added to the page, instead\n of the task. This behavior is not good, but is compatible with legacy usages of task metadata, which should not break\n some existing queries.\n - This behavior will be removed in the future behind a flag.\n- Added the 'visual' field to tasks - if set, tasks render 'visual' instead of their regular text.\n- Fixed `DataArray#mutate()`.\n\n---\n\n# 0.5.0 (Beta)\n\nRe-release of broken release 0.4.23, now hopefully with fixes that make it work on (most) machines. I'll be doing beta\nreleases for a little while until I can confirm the new version is stable; use BRAT\n(https://github.com/TfTHacker/obsidian42-brat) to easily track Dataview beta versions if you are interested in cutting\nedge features.\n\n---\n\n# 0.4.25\n\nFix #867: Create a container div per taskList to allow for multiple task views.\n\n---\n\n# 0.4.24\n\nRe-release of 0.4.23f since Obsidian does not automatically update between non-semver versions.\n\n---\n\n# 0.4.23f\n\nRemove some code which attempted to make tag queries case-insensitive; I'll reimplement this more generally later (it\nconflicts with existing queries which check tags via `contains(file.tags, \"#Tag\")` and similar).\n\n---\n\n# 0.4.23e\n\nMore task bugfixes / improvements, and a fix that caused task metadata to be duplicated.\n\n---\n\n# 0.4.23d\n\nMore inline field list parsing bug fixes. Hopefully we're back to a nice working order!\n\n---\n\n# 0.4.23c\n\nBugfix which adds support for '1)' style lists, as well as a very annoying null issue due to JavaScript being a very\nsad, very sad language.\n\n---\n\n# 0.4.23b\n\nBugfix for bad inlink/outlink computations; links were not being normalized properly so reverse lookups were not\nworking.\n\n---\n\n# 0.4.23\n\nThe Task Update! This release reworks how dataview handles tasks and list items so that they should be much more\nintuitive to use and interact with:\n\n1. **Subtask Support**: Queries now search over all list items, instead of only over root elements. This should make\n task filtering much more usable, especially if you tend to put tasks under other list items or care specifically\n about subtasks.\n2. **Multiline Support**: Dataview now understands multi-line tasks and renders/updates them correctly.\n3. **Immediately Navigate to Task**: The new task view, aside from looking a little cleaner than previous views, now\n immediately navigates to the task in it's original file on click and selects it.\n4. **Grouping Support**: For DataviewJS users, `dv.taskList` now supports grouping (as produced by `groupBy` and the new\n `groupIn`) natively.\n\nFor DataviewJS users, the task and list representation has changed: `file.tasks` (and the new `file.lists`) contain\nevery single task (including subtasks) in the file, instead of only the root elements. You can return to previous\nbehavior by filtering out tasks with a non-null parent - i.e., `file.tasks.where(task => !task.parent)`. `dv.taskList`\nwill intelligently deal with properly nesting and de-duplicating tasks, so just filter to the tasks you want to render and\nthe API will do the rest.\n\nThis release also includes general backend improvements as we prepare for live-editing in Dataview views, as well as\nseveral community-contributed API improvements:\n\n- `DataArray#groupIn`: For grouping already grouped data, you can now use `array.groupIn(v => ...)`, which will group\n the innermost (original) data in the array instead of the top level groups. This allows for more easily grouping\n recursively, such as `dv.pages().groupBy(page => page.file.folder).groupIn(page => page.title)` producing a grouping\n of folders, then page titles.\n- `substring(string, start[, end])`: The last major missing string function is now available! Take slices of strings.\n- Improved `dv.el()` and other HTML functions - thanks @vitaly.\n- null and undefined entries sort at the end instead of the beginning by default; sorry to those whose code sorts wrong\n because of this, but it is a better default for most people's use cases.\n- All links are now properly normalized to their full paths, fixing many link comparison edge cases in DataviewJS.\n\nDocumentation additions for the new task functionality will be coming out in the next few days. The next release 0.4.24\nis currently targeting expanded `FROM` query support, basic table view improvements, and general exporting functionality\nfor Dataview. See you then!\n\n---\n\n# 0.4.22\n\nThe @pjeby update! This includes several performance improvements suggested by @pjeby to dramatically improve background\nDataview performance as well as reduce some memory pressure. It also includes some minor bug-fixes and preliminary\nfunctionality:\n\n- Target ES2018 for better Promise support\n- Allow parsing shorthands in `dv.date()`.\n- Add additional metadata to inline field rendering which can be styled.\n- Cleanup events & workers on plugin uninstall, improving the Dataview uninstall/disable/reload experience.\n- Add preliminary `CALENDAR` queries - rendering similar to the obsidian-calendar plugin, see the documentation!\n\nDataview should perform much better on startup and when you have lots of tabs open - thanks again to @pjeby.\n\n---\n\n# 0.4.21\n\nBugfix release which primarily fixes issues that Dataview had with the live preview mode in upcoming Obsidian versions;\nDataview live preview should now be functional. Also includes a number of smaller bugfixes.\n\n- Fix #646: Add `date(yesterday)` to create a date 24 hours ago.\n- Fix #618: Luxon is now available on the dataview API (`dv.luxon`).\n- Fix #510: Add `dv.duration()` for parsing durations.\n- Fix #647: All HTML functions in the DataviewJS API now return their rendered objects.\n- Fix #652: Fix parsing of invalid dates.\n- Fix #629: Fix block link parsing.\n- Fix #601: Timezones are now rendered properly and parsed properly in Dataview dates.\n- PR #637: Add `meta(link)` which allows you to access various metadata about a link itself.\n- Various minor null safety fixes.\n- Dataview now reports it's exact version and build time in logs.\n\n---\n\n# 0.4.20\n\nSome feature work (mostly by other contributors) while I while away at section metadata. May also fix a few bugs!\n\n- Fix #448: You can now use the \"Task Completion Tracking\" option to automatically add completion metadata to tasks\n which are checked/unchecked through Dataview. Thanks to @sheeley.\n- Add a search bar to documentation. Thanks to @tzhou.\n- Add new date expressions for the start of the week (`date(sow)`), and the end of the week (`date(eow)`). Thanks\n @Jeamee and @v_mujunma.\n\nSmall minor bugfix / security releases may follow in the near future; otherwise, the next major release will include\nsection and object metadata.\n\n---\n\n# 0.4.19\n\nBugfix release which corrects emoji parsing & localization issues.\n\n- Add `DataArray#into`, which lets you index into objects without flattening.\n- Renamed 'header' to 'section' in task metadata; 'header' will remain around for a few major releases to let people\n naturally migrate.\n- Fix #487: You no longer need spaces around '*' in expressions.\n- Fix #559: Fix unicode issues in variable canonicalization which was causing problems with non-Latin inline field\n keys.\n\n## Duration Parsing\n\nYou can now include multiple units in durations: `dur(8 minutes, 4 seconds)` or `dur(2yr8mo12d)`. You can separate\ndurations by commas, or use the abbreviated syntax with/without spaces.\n\n---\n\n# 0.4.18\n\nBugfix release which fixes bad inline field highlighting if '[' and '(' are mixed on the same line in particular orders.\n\n---\n\n# 0.4.17\n\nMinor feature release to patch up more implementation holes.\n\n## Single File Queries\n\nYou can now query from a specific file (instead of just folders and tags) by specifying the full file path:\n\n```\nTASK FROM \"dataview/Test\"\n...\n```\n\nThis is primarily useful for task queries, but will soon be useful for section and object queries in the near future as\nwell.\n\n## Better Inline Field Highlighting\n\nThe CSS for inline field highlighting has been fixed and some compatibility issues improved, so it should work on all\nthemes now instead of only a few.\n\n## dv.el()\n\nDataviewJS now has `dv.el()`, which is like existing functions like `dv.paragraph` and `dv.span` but can create any\nHTML element type; for example:\n\n```js\ndv.el(\"b\", \"Text!\");\ndv.el(\"i\", 18);\n```\n\n---\n\n# 0.4.16\n\nSmall performance release which substantially reduces the impact Dataview has on vault loading times (by spreading out\nfile loading). The Dataview Index is now also eagerly initialized, so plugin consumers of the API can immediately start\nusing it instead of waiting for the `dataview:api-ready` event.\n\n---\n\n# 0.4.15\n\nA simple fix for #537 which properly 'awaits' value rendering in `dv.view()`. Fixes issues with values rendering out of\norder.\n\n---\n\n# 0.4.14\n\nSmall bugfix release.\n\n- Fixes inline field evaluation when using the new fancy highlighting.\n- You can now configure whether task links should show up at the beginning or end of the task (or just disable them)\n in the \"Task Link Location\" setting.\n- Most setting updates will immediately be applied to existing Dataviews.\n\n---\n\n# 0.4.13\n\nBugfix release which adds fancy rendering to inline-inline fields and includes a few bugfixes.\n\n## Pretty Inline Fields\n\nInline fields of the form `[key:: value]` will now be rendered with fancy new HTML! By default, they are rendered with\nboth the key and value. You can only render the value using parenthesis instead: `(key:: value)`. You can disable\nthis feature in the configuration.\n\nFull-line inline fields (that Dataview has supported for a long time) will gain similar rendering support soon; in the\nmeanwhile, give the new syntax a try!\n\n### Task Linking\n\nTasks now render with a link to the page/section that they are defined in, making `GROUP BY` and custom task\nediting easier to do:\n\n- [ ] A Task. 🔗\n- [ ] Another Task. 🔗\n - [ ] Some Random Subtask. 🔗\n\nYou can configure the symbol for the link or disable it altogether.\n\n### Improving DataviewJS Posture\n\nI am currently actively looking into improving DataviewJS sandboxing and general security posture. As a first small step\nin this, I have made DataviewJS opt-in instead of opt-out, and added a separate control for Inline DataviewJS. You may\nneed to re-enable it in your settings if you use it.\n\nMore improvements and better JavaScript sandboxing will follow.\n\n---\n\n# 0.4.12-hotfix1\n\nRe-release of 0.4.12 that fixes an important indexing issue.\n\n- Fix #505: Use `completion` instead of `completed` when setting task completion time.\n- Fix #509: Add `startswith` / `endswith` string functions.\n- Fix #488: Add `padleft` and `padright`, and `string`.\n- Fix #506, #512: Fix date comparisons due to a bizarre date zone issue.\n\n---\n\n# 0.4.12\n\nBugfix release following up 0.4.11 which includes a few minor function additions.\n\n- Fix #512: Strange zone issue causing dates to not be equal.\n- Fix #506: Same as #512.\n- Fix #488: Add `padleft` / `padright` functions.\n- Fix #509: Add `startswith` and `endswith` functions.\n- Fix #505: Correctly read completion dates for tasks from `completion`.\n\nThis release also includes improved testing thanks to mocking Obsidian plugin APIs!\n\n---\n\n# 0.4.11\n\nFixes task behavior and adds \"truly inline\" fields!\n\n## Improved Task Behavior\n\nTask queries are now much improved from their primitive foundations - you can now filter, sort, and group them! The FROM\nblock is still page-based, sadly, though you can simply use `WHERE` instead if desired. For example, you can now access\ntask fields like `text`, `line`, or `completed`:\n\n```\nTASK WHERE contains(text, \"#tag\")\nWHERE !completed\nGROUP BY file.folder\n```\n\nThe full list of all available task metadata can be found\n[here](https://blacksmithgu.github.io/obsidian-dataview/data-annotation/#tasks); tasks include all the information\nneeded to uniquely identify them, and automatically inherit all of the metadata from their parent file as well (so you\ncan access `file.name`, for example). You can also annotate tasks with inline fields, as described in the section below.\n\nThere is some additional UX work to be done - primarily on more easily allowing you to navigate to where the task is\ndefined, as well as render tasks in views other than the `TASK` view. The semantics of how grouping works (to make it\nmore intuitive/useful than it currently is) will likely also be revisited.\n\n## Inline Inline Fields\n\nEarly support for truly inline fields have been added, where you can add metadata in the middle of a sentence. It looks\nsimilar to existing inline field syntax, but with brackets or parenthesis:\n\n```\nI would rate this a [rating:: 6]. It was (thoughts:: acceptable).\n```\n\nImproved rendering for all inline fields is coming in an upcoming update to improve the visual look of these inline\nfields.\n\n\n## Issues\n\n- Fix #496: Fix task `SORT` functionality to do something.\n- Fix #492: Tasks now properly annotated with parent file information.\n- Fix #498: Fix task checking/unchecking logic (which broke due to a change in the task regex...).\n\n---\n\n# Initial\n\nStart of the automatic changelog.\n"
},
{
"path": "LICENSE.txt",
"content": "MIT License\n\nCopyright (c) 2021 Michael Brenan\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE."
},
{
"path": "README.md",
"content": "# Obsidian Dataview\n\nTreat your [Obsidian Vault](https://obsidian.md/) as a database which you can query from. Provides a JavaScript API and\npipeline-based query language for filtering, sorting, and extracting data from Markdown pages. See the Examples section\nbelow for some quick examples, or the full [reference](https://blacksmithgu.github.io/obsidian-dataview/) for all the details.\n\n## Examples\n\nShow all games in the game folder, sorted by rating, with some metadata:\n\n~~~markdown\n```dataview\ntable time-played, length, rating\nfrom \"games\"\nsort rating desc\n```\n~~~\n\n\n\n---\n\nList games which are MOBAs or CRPGs.\n\n~~~markdown\n```dataview\nlist from #game/moba or #game/crpg\n```\n~~~\n\n\n\n---\n\nList all markdown [tasks](https://blacksmithgu.github.io/obsidian-dataview/data-annotation/#tasks) in un-completed projects:\n\n~~~markdown\n```dataview\ntask from #projects/active\n```\n~~~\n\n\n\n---\n\nShow all files in the `books` folder that you read in 2021, grouped by genre and sorted by rating:\n\n~~~markdown\n```dataviewjs\nfor (let group of dv.pages(\"#book\").where(p => p[\"time-read\"].year == 2021).groupBy(p => p.genre)) {\n\tdv.header(3, group.key);\n\tdv.table([\"Name\", \"Time Read\", \"Rating\"],\n\t\tgroup.rows\n\t\t\t.sort(k => k.rating, 'desc')\n\t\t\t.map(k => [k.file.link, k[\"time-read\"], k.rating]))\n}\n```\n~~~\n\n\n\n## Usage\n\nFor a full description of all features, instructions, and examples, see the [reference](https://blacksmithgu.github.io/obsidian-dataview/). For a more brief outline, let us examine the two major aspects of Dataview: *data* and *querying*.\n\n#### **Data**\n\nDataview generates *data* from your vault by pulling\ninformation from **Markdown frontmatter** and **Inline fields**.\n\n- Markdown frontmatter is arbitrary YAML enclosed by `---` at the top of a markdown document which can store metadata\n about that document.\n- Inline fields are a Dataview feature which allow you to write metadata directly inline in your markdown document via\n `Key:: Value` syntax.\n\nExamples of both are shown below:\n\n```yaml\n---\nalias: \"document\"\nlast-reviewed: 2021-08-17\nthoughts:\n rating: 8\n reviewable: false\n---\n```\n```markdown\n# Markdown Page\n\nBasic Field:: Value\n**Bold Field**:: Nice!\nYou can also write [field:: inline fields]; multiple [field2:: on the same line].\nIf you want to hide the (field3:: key), you can do that too.\n```\n\n#### **Querying**\n\nOnce you've annotated documents and the like with metadata, you can then query it using any of Dataview's four query\nmodes:\n\n1. **Dataview Query Language (DQL)**: A pipeline-based, vaguely SQL-looking expression language which can support basic\n use cases. See the [documentation](https://blacksmithgu.github.io/obsidian-dataview/query/queries/) for details.\n\n ~~~markdown\n ```dataview\n TABLE file.name AS \"File\", rating AS \"Rating\" FROM #book\n ```\n ~~~\n\n2. **Inline Expressions**: DQL expressions which you can embed directly inside markdown and which will be evaluated in\n preview mode. See the [documentation](https://blacksmithgu.github.io/obsidian-dataview/reference/expressions/) for\n allowable queries.\n\n ```markdown\n We are on page `= this.file.name`.\n ```\n\n3. **DataviewJS**: A high-powered JavaScript API which gives full access to the Dataview index and some convenient\n rendering utilities. Highly recommended if you know JavaScript, since this is far more powerful than the query\n language. Check the [documentation](https://blacksmithgu.github.io/obsidian-dataview/api/intro/) for more details.\n\n ~~~markdown\n ```dataviewjs\n dv.taskList(dv.pages().file.tasks.where(t => !t.completed));\n ```\n ~~~\n\n4. **Inline JS Expressions**: The JavaScript equivalent to inline expressions, which allow you to execute arbitrary JS\n inline:\n\n ~~~markdown\n This page was last modified at `$= dv.current().file.mtime`.\n ~~~\n\n#### JavaScript Queries: Security Note\n\nJavaScript queries are very powerful, but they run at the same level of access as any other Obsidian plugin. This means\nthey can potentially rewrite, create, or delete files, as well as make network calls. You should generally write\nJavaScript queries yourself or use scripts that you understand or that come from reputable sources. Regular Dataview\nqueries are sandboxed and cannot make negative changes to your vault (in exchange for being much more limited).\n\n## Contributing\n\nContributions via bug reports, bug fixes, documentation, and general improvements are always welcome. For more major\nfeature work, make an issue about the feature idea / reach out to me so we can judge feasibility and how best to\nimplement it.\n\n#### Local Development\n\nThe codebase is written in TypeScript and uses `rollup` / `node` for compilation; for a first time set up, all you\nshould need to do is pull, install, and build:\n\n```console\nfoo@bar:~$ git clone git@github.com:blacksmithgu/obsidian-dataview.git\nfoo@bar:~$ cd obsidian-dataview\nfoo@bar:~/obsidian-dataview$ npm install\nfoo@bar:~/obsidian-dataview$ npm run dev\n```\n\nThis will install libraries, build dataview, and deploy it to `test-vault`, which you can then open in Obsidian. This\nwill also put `rollup` in watch mode, so any changes to the code will be re-compiled and the test vault will automatically\nreload itself.\n\n#### Preparing for creating pull requests\n\nIf you plan on doing pull request, we would also recommend to do the following in advance of creating the pull request:\n\n```console\nfoo@bar:~$ npm run dev\nfoo@bar:~$ npm run check-format\nfoo@bar:~$ npm run format\nfoo@bar:~$ npm run test\n```\n\nThe third step of `npm run format` is only needed if the format check reports some issue.\n\n#### Installing to Other Vaults\n\nIf you want to dogfood dataview in your real vault, you can build and install manually. Dataview is predominantly a\nread-only store, so this should be safe, but watch out if you are adjusting functionality that performs file edits!\n\n```console\nfoo@bar:~/obsidian-dataview$ npm run build\nfoo@bar:~/obsidian-dataview$ ./scripts/install-built path/to/your/vault\n```\n\n#### Building Documentation\n\nWe use `MkDocs` for documentation (found in `docs/`). You'll need to have python and pip to run it locally:\n\n```console\nfoo@bar:~/obsidian-dataview$ pip3 install mkdocs mkdocs-material mkdocs-redirects\nfoo@bar:~/obsidian-dataview$ cd docs\nfoo@bar:~/obsidian-dataview/docs$ mkdocs serve\n```\n\nThis will start a local web server rendering the documentation in `docs/docs`, which will live-reload on change.\nDocumentation changes are automatically pushed to `blacksmithgu.github.io/obsidian-dataview` once they are merged\nto the main branch.\n\n#### Using Dataview Types In Your Own Plugin\n\nDataview publishes TypeScript typings for all of its APIs onto NPM (as `blacksmithgu/obsidian-dataview`). For\ninstructions on how to set up development using Dataview, see [setup instructions](https://blacksmithgu.github.io/obsidian-dataview/plugin/develop-against-dataview/).\n\n## Support\n\nHave you found the Dataview plugin helpful, and want to support it? I accept donations which go towards future\ndevelopment efforts. I generally do not accept payment for bug bounties/feature requests, as financial incentives add\nstress/expectations which I want to avoid for a hobby project!\n\nSupport @blacksmithgu: \n[](https://www.paypal.com/donate?business=Y9SKV24R5A8BQ&item_name=Open+source+software+development¤cy_code=USD)\n\nSupport @holroy: \n(file: TFile): Promise {\n let contents = await this.vault.read(file);\n let metadata = await this.metadataCache.getFileCache(file);\n return runImport(file.path, contents, file.stat, metadata as CachedMetadata) as any as T;\n }\n}\n"
},
{
"path": "__mocks__/obsidian.ts",
"content": "import EventEmitter from \"events\";\n\n/** Basic obsidian abstraction for any file or folder in a vault. */\nexport abstract class TAbstractFile {\n /**\n * @public\n */\n vault: Vault;\n /**\n * @public\n */\n path: string;\n /**\n * @public\n */\n name: string;\n /**\n * @public\n */\n parent: TFolder;\n}\n\n/** Tracks file created/modified time as well as file system size. */\nexport interface FileStats {\n /** @public */\n ctime: number;\n /** @public */\n mtime: number;\n /** @public */\n size: number;\n}\n\n/** A regular file in the vault. */\nexport class TFile extends TAbstractFile {\n stat: FileStats;\n basename: string;\n extension: string;\n}\n\n/** A folder in the vault. */\nexport class TFolder extends TAbstractFile {\n children: TAbstractFile[];\n\n isRoot(): boolean {\n return false;\n }\n}\n\nexport class Vault extends EventEmitter {\n getFiles() {\n return [];\n }\n trigger(name: string, ...data: any[]): void {\n this.emit(name, ...data);\n }\n}\n\nexport class Component {\n registerEvent() {}\n}\n"
},
{
"path": "cspell.json",
"content": "{\n \"version\": \"0.2\",\n \"ignorePaths\": [],\n \"dictionaryDefinitions\": [],\n \"dictionaries\": [],\n \"words\": [\n \"aaab\",\n \"akey\",\n \"alexfertel\",\n \"AnnaKornfeldSimpson\",\n \"apng\",\n \"artisticat\",\n \"autorelease\",\n \"bcbe\",\n \"bimap\",\n \"binaryop\",\n \"bkey\",\n \"blacksmithgu\",\n \"Brenan\",\n \"bryc\",\n \"callouts\",\n \"canonicalization\",\n \"canonicalize\",\n \"CANONICALIZER\",\n \"canonicalizes\",\n \"canonicalizing\",\n \"carlesalbasboix\",\n \"cday\",\n \"charleshan\",\n \"Cheatsheet\",\n \"Cheatsheets\",\n \"Chouffy\",\n \"clsname\",\n \"codemirror\",\n \"combinators\",\n \"compday\",\n \"comptime\",\n \"concat\",\n \"containsword\",\n \"crashy\",\n \"cres\",\n \"crog\",\n \"crpg\",\n \"cssclasses\",\n \"currencyformat\",\n \"cyrb\",\n \"dailys\",\n \"datapoints\",\n \"Datarow\",\n \"Dataview\",\n \"dataviewjs\",\n \"Dataviews\",\n \"datefield\",\n \"ddd\",\n \"DDTHH\",\n \"début\",\n \"dedup\",\n \"dformat\",\n \"dogfood\",\n \"Donadio\",\n \"dtformat\",\n \"duedate\",\n \"dueday\",\n \"duetime\",\n \"durationformat\",\n \"dvjs\",\n \"econtains\",\n \"elink\",\n \"embeddable\",\n \"endswith\",\n \"errorbox\",\n \"etags\",\n \"Evals\",\n \"eyuelt\",\n \"failable\",\n \"fastfood\",\n \"fdefault\",\n \"fileset\",\n \"Filetext\",\n \"Filipe\",\n \"frontmatter\",\n \"fullscan\",\n \"functionname\",\n \"GamerGirlandCo\",\n \"gdhjg\",\n \"gentlegiantJGC\",\n \"Gott\",\n \"Groot\",\n \"helloxx\",\n \"Hoeven\",\n \"holroy\",\n \"iamrecursion\",\n \"icontains\",\n \"iden\",\n \"ifield\",\n \"iitem\",\n \"implicits\",\n \"INDEXEDDB\",\n \"Ingrouped\",\n \"Inlines\",\n \"inlink\",\n \"inlinks\",\n \"Jeamee\",\n \"jfif\",\n \"Kanban\",\n \"kometenstaub\",\n \"ldefault\",\n \"leoccyao\",\n \"lezer\",\n \"Linkpath\",\n \"localforage\",\n \"localtime\",\n \"longkeyidontneedwhenreading\",\n \"lres\",\n \"luxon\",\n \"lwrap\",\n \"MarioRicalde\",\n \"matchreg\",\n \"maxby\",\n \"mday\",\n \"meello\",\n \"meep\",\n \"Millis\",\n \"minby\",\n \"mkdocs\",\n \"mnaoumov\",\n \"moba\",\n \"mobas\",\n \"mocsa\",\n \"mt-krainski\",\n \"mvalues\",\n \"nestedfield\",\n \"nonnull\",\n \"noopener\",\n \"Nums\",\n \"offref\",\n \"onwarn\",\n \"ooker777\",\n \"outlink\",\n \"outlinks\",\n \"padleft\",\n \"padright\",\n \"Pagerow\",\n \"papaparse\",\n \"parsimmon\",\n \"pathlike\",\n \"pjeby\",\n \"pjepg\",\n \"pleh\",\n \"preact\",\n \"protofarer\",\n \"proxied\",\n \"pymdownx\",\n \"RaviOnline\",\n \"rawlink\",\n \"recurkey\",\n \"Refreshable\",\n \"REGEXES\",\n \"regexmatch\",\n \"regexreplace\",\n \"regextest\",\n \"renderable\",\n \"Repr\",\n \"RyotaUshio\",\n \"sandboxed\",\n \"sandboxing\",\n \"seanlzx\",\n \"sheeley\",\n \"sohanglal\",\n \"somemetadata\",\n \"somidad\",\n \"spoopy\",\n \"Stardew\",\n \"startswith\",\n \"steamid\",\n \"steg\",\n \"striptime\",\n \"subargs\",\n \"subcontainer\",\n \"subeval\",\n \"subfolders\",\n \"sublists\",\n \"Subsettings\",\n \"subsources\",\n \"subtag\",\n \"Subtags\",\n \"subvalue\",\n \"subword\",\n \"succ\",\n \"superfences\",\n \"tasklist\",\n \"tcopy\",\n \"Templater\",\n \"Testcase\",\n \"toolbelt\",\n \"trunc\",\n \"typeof\",\n \"tzhou\",\n \"unindented\",\n \"unrendered\",\n \"v_mujunma\",\n \"vals\",\n \"vararg\",\n \"varargs\",\n \"vectorize\",\n \"vitaly\",\n \"vpos\",\n \"vrtmrz\",\n \"weekyear\",\n \"whitespaces\",\n \"xxhello\",\n \"ymdh\",\n \"ymdhm\",\n \"ymdhms\",\n \"zerollup\",\n \"Статус\"\n ],\n \"ignoreWords\": [],\n \"import\": [],\n \"enabled\": true\n}\n"
},
{
"path": "docs/.gitignore",
"content": "site/\n"
},
{
"path": "docs/docs/annotation/add-metadata.md",
"content": "# Adding Metadata to your Pages\n\nDataview cannot query all content of your vault. In order to be able to search, filter and display content, this content needs to be **indexed**. Some content is indexed automatically, like bullet points or task lists - so called **Implicit fields**, more on that below - and other data needs to be saved in a metadata **field** to be accessible through dataview. \n\n## What is a \"field\"?\n\nA metadata field is a pair of a **key** and a **value**. The _value_ of a field has a data type (more on that [here](./types-of-metadata.md)) that determines how this field will behave when querying it. \n\nYou can add any number of fields to a **note**, a **list item** or a **task**. \n\n## How do I add fields?\n\nYou can add fields to a **note** in three different ways. How a field look like depends on the way you add it.\n\nOn **tasks or list items**, you will have YAML Frontmatter information available, but won't be able to add them to a specific list item. If you want to add metadata to one list item or task only, use [Inline Fields](#inline-fields).\n\n### Frontmatter\n\nFrontmatter is a common Markdown extension which allows for YAML metadata to be added to the top of a page. It is natively supported by Obsidian and explained in its [official documentation](https://help.obsidian.md/Advanced+topics/YAML+front+matter). All YAML Frontmatter fields will be automatically available as Dataview fields.\n\n```yaml\n ---\n alias: \"document\"\n last-reviewed: 2021-08-17\n thoughts:\n rating: 8\n reviewable: false\n ---\n```\n\nWith this your note has metadata fields named `alias`, `last-reviewed`, and `thoughts`. Each of these have different **data types**:\n\n- `alias` is a [text](types-of-metadata.md#text), because its wrapped in \"\"\n- `last-reviewed` is a [date](types-of-metadata.md#date), because it follows the ISO date format\n- `thoughts` is a [object](types-of-metadata.md#object) field, because it uses the YAML Frontmatter object syntax\n\nYou could query for this note with the following query:\n\n~~~\n```dataview\nLIST\nWHERE thoughts.rating = 8\n```\n~~~\n\n### Inline Fields\n\nFor those wanting a more natural-looking annotation, Dataview supports \"inline\" fields via a `Key:: Value` syntax that you can use everywhere in your file. This allows you to write your queryable data right where you need it - for example in the middle of a sentence. \n\nIf your inline field has an own line, without any content beforehand, you can write it like this: \n\n```markdown\n# Markdown Page\n\nBasic Field:: Some random Value\n**Bold Field**:: Nice!\n```\n\nAll content after the `::` is the value of the field until the next line break.\n\n!!! hint \"Mind the `::`\"\n Note that you need to use a double colon `::` between key and value when using inline fields, contrary to YAML Frontmatter fields where one colon is enough. \n\nIf you want to embed metadata inside sentences, or multiple fields on the same line, you can use the bracket syntax and wrap your field in square brackets:\n\n```markdown\nI would rate this a [rating:: 9]! It was [mood:: acceptable].\n```\n\n!!! info \"Fields on list items and tasks\"\n When you want to annotate a list item, e.g. a task, with metadata, you always need to use the bracket syntax (because the field is not the only information in this line)\n ```markdown\n - [ ] Send an mail to David about the deadline [due:: 2022-04-05].\n ```\n Bracketed inline fields are the only way to explicitly add fields to specific list items, YAML frontmatter always applies to the whole page (but is also available in context of list items.)\n\nThere is also the alternative parenthesis syntax, which hides the key when\nrendered in Reader mode:\n\n```markdown\nThis will not show the (longKeyIDontNeedWhenReading:: key).\n```\n\nwill render to:\n\n```markdown\nThis will not show the key.\n```\n\nYou can use YAML Frontmatter and Inline fields with all syntax variants together in one file. You do not need to decide for one and can mix them to fit your workflow.\n\n## Field names\n\nImagine you used all the examples for Inline fields you see above in one note, then following metadata would be available to you:\n\n| Metadata Key | Sanitized Metadata key | Value | Data Type of Value |\n| ----------- | ------------------------|----------- | ----------- |\n| `Basic Field` | `basic-field` | Some random Value | Text |\n| `Bold Field` | `bold-field` | Nice! | Text |\n| `rating` | - | 9 | Number |\n| `mood` | - | acceptable | Text |\n| `due` | - | Date Object for 2022-04-05 | Date |\n| `longKeyIDontNeedWhenReading` | `longkeyidontneedwhenreading` | key | Text |\n\nLike you can see in the table, if you are using **spaces or capitalized letters** in your metadata key name, dataview will provide you with a **sanitized version** of the key. \n\n**Keys with spaces** cannot be used in a query as-is. You have two possibilities here: Either use the sanitized name, that is always all lowercase and with dashes instead of spaces or use the **row** variable syntax. Find out more [in the FAQ](../resources/faq.md).\n\n**Keys with capitalized letters** can be used as-is, if you wish. The sanitized version allows you to query for a key independent of its capitalization and makes it easier to use: You can query the same field that's, for example, in one file named `someMetadata` and in another `someMetaData` when using the sanitized key `somemetadata`. \n\nIn addition, the **bold field key is missing its formatting tokens**. Even though the `**` used to make it appear bold are part of the key name in the file, they are left out when indexing your note. The same goes for all other built-in formatting, like strike through or italic. This means formatted keys can only be queried without their formatting. This allows you to format the key in context of the note without worrying that you might create different keys for the same type of information. \n\n### Usage of emojis and non-latin characters\n\nYou are not limited to latin characters when naming your metadata fields. You can use all characters available in UTF-8:\n\n```markdown\nNoël:: Un jeu de console\nクリスマス:: 家庭用ゲーム機\n[🎅:: a console game]\n[xmas🎄:: a console game]\n```\n\n**Using emojis as metadata keys** is possible, but it comes with some limitations. When using emojis in field names, you need to put them into square brackets so that dataview recognize them correctly. \nAlso, please be aware when switching the OS (i.e. from Windows to Android), the same emoji could use another character code and you might not find your metadata when querying it.\n\n!!! info \"Task Field Shorthands\"\n An exception to this are the [shorthand syntax](./metadata-tasks.md#field-shorthands) in Tasks. You can use shorthands without bracketing. Please mind though that this only counts for listed shorthands - every other field (if with emojis or not) need to use the `[key:: value]` syntax.\n\n## Implicit fields\n\nEven if you do not add any metadata explicitly to your note, dataview provides you with a big amount of indexed data out of the box. Some examples for implicit fields are:\n\n- day the file was created (`file.cday`)\n- links in the file (`file.outlinks`)\n- tags in the file (`file.etags`)\n- all list items in the file (`file.lists` and `file.tasks`)\n\nand many more. Available implicit fields differ depending if you look at a page or a list item. Find the full list of available implicit fields on [Metadata on pages](metadata-pages.md) and [Metadata on Tasks and Lists](metadata-tasks.md).\n"
},
{
"path": "docs/docs/annotation/metadata-pages.md",
"content": "# Metadata on Pages\n\nYou can add fields to a markdown page (a note) in three different ways - via Frontmatter, Inline fields and Implicit fields. Read more about the first two possibilities in [\"how to add metadata\"](./add-metadata.md).\n\n## Implicit Fields\n\nDataview automatically adds a large amount of metadata to each page. These implicit and automatically added fields are collected under the field `file`. Following are available:\n\n| Field Name | Data Type | Description |\n| --------------------- | --------- | ----------- |\n| `file.name` | Text | The file name as seen in Obsidians sidebar. |\n| `file.folder` | Text | The path of the folder this file belongs to. |\n| `file.path` | Text | The full file path, including the files name. |\n| `file.ext` | Text | The extension of the file type; generally `md`. |\n| `file.link` | Link | A link to the file. |\n| `file.size` | Number | The size (in bytes) of the file. |\n| `file.ctime` | Date with Time | The date that the file was created. |\n| `file.cday` | Date | The date that the file was created. |\n| `file.mtime` | Date with Time | The date that the file was last modified. |\n| `file.mday` | Date | The date that the file was last modified. |\n| `file.tags` | List | A list of all unique tags in the note. Subtags are broken down by each level, so `#Tag/1/A` will be stored in the list as `[#Tag, #Tag/1, #Tag/1/A]`. |\n| `file.etags` | List | A list of all explicit tags in the note; unlike `file.tags`, does not break subtags down, i.e. `[#Tag/1/A]` |\n| `file.inlinks` | List | A list of all incoming links to this file, meaning all files that contain a link to this file. |\n| `file.outlinks` | List | A list of all outgoing links from this file, meaning all links the file contains. |\n| `file.aliases` | List | A list of all aliases for the note as defined via the [YAML frontmatter](https://help.obsidian.md/How+to/Add+aliases+to+note). |\n| `file.tasks` | List | A list of all tasks (I.e., `| [ ] some task`) in this file. |\n| `file.lists` | List | A list of all list elements in the file (including tasks); these elements are effectively tasks and can be rendered in task views. |\n| `file.frontmatter` | List | Contains the raw values of all frontmatter in form of `key | value` text values; mainly useful for checking raw frontmatter values or for dynamically listing frontmatter keys. |\n| `file.day` | Date | Only available if the file has a date inside its file name (of form `yyyy-mm-dd` or `yyyymmdd`), or has a `Date` field/inline field. |\n| `file.starred` | Boolean | If this file has been bookmarked via the Obsidian Core Plugin \"Bookmarks\". |\n\n## Example page\n\nThis is a small Markdown page which includes both user-defined ways to add metadata:\n\n```markdown\n---\ngenre: \"action\"\nreviewed: false\n---\n# Movie X\n#movies\n\n**Thoughts**:: It was decent.\n**Rating**:: 6\n\n[mood:: okay] | [length:: 2 hours]\n```\n\nIn addition to the values you see here, the page has also all keys listed above available.\n\n### Example Query\n\nYou can query part of the above information with following query, for example:\n\n~~~yaml\n```dataview\nTABLE file.ctime, length, rating, reviewed\nFROM #movies\n```\n~~~\n"
},
{
"path": "docs/docs/annotation/metadata-tasks.md",
"content": "# Metadata on Tasks and Lists\n\nJust like pages, you can also add **fields** on list item and task level to bind it to a specific task as context. For this you need to use the [inline field syntax](add-metadata.md#inline-fields):\n\n```markdown\n- [ ] Hello, this is some [metadata:: value]!\n- [X] I finished this on [completion:: 2021-08-15].\n```\n\nTasks and list items are the same data wise, so all your bullet points have all the information described here available, too.\n\n## Field Shorthands\n\nThe [Tasks](https://publish.obsidian.md/tasks/Introduction) plugin introduced a different [notation by using Emoji](https://publish.obsidian.md/tasks/Reference/Task+Formats/Tasks+Emoji+Format) to configure the different dates related to a task. In the context of Dataview, this notation is called `Field Shorthands`. The current version of Dataview only support the dates shorthands as shown below. The priorities and recurrence shorthands are not supported.\n\n=== \"Example\"\n\n\n=== \"Example\"\n - [ ] Due this Saturday 🗓️2021-08-29\n - [x] Completed last Saturday ✅2021-08-22\n - [ ] I made this on ➕1990-06-14\n - [ ] Task I can start this weekend 🛫2021-08-29\n - [x] Task I finished ahead of schedule ⏳2021-08-29 ✅2021-08-22\n\nThere are two specifics to these emoji-shorthands. First, they omit the inline field syntax (no `[🗓️:: YYYY-MM-DD]` needed) and secondly, they map to a **textual** field name data-wise:\n\n| Field name | Short hand syntax |\n| ---------- | ----------------- |\n| due | `🗓️YYYY-MM-DD` |\n| completion | `✅YYYY-MM-DD` |\n| created | `➕YYYY-MM-DD` |\n| start | `🛫YYYY-MM-DD` |\n| scheduled | `⏳YYYY-MM-DD` |\n\nThis means if you want to query for all tasks that are completed 2021-08-22, you'll write:\n\n~~~markdown\n```dataview\nTASK\nWHERE completion = date(\"2021-08-22\")\n```\n~~~\n\nWhich will list both variants - shorthands and textual annotation:\n\n```markdown\n- [x] Completed last Saturday ✅2021-08-22\n- [x] Some Done Task [completion:: 2021-08-22]\n```\n\n## Implicit Fields\n\nAs with pages, Dataview adds a number of implicit fields to each task or list item:\n\n!!! info \"Inheritance of Fields\"\n Tasks inherit *all fields* from their parent page - so if you have a `rating` field in your page, you can also access it on your task in a `TASK` Query.\n\n\n| Field name | Data Type | Description |\n| ---------- | --------- | ----------- |\n| `status` | Text | The completion status of this task, as determined by the character inside the `[ ]` brackets. Generally a space `\" \"` for incomplete tasks and an `\"x\"` for completed tasks, but allows for plugins which support alternative task statuses. |\n| `checked` | Boolean | Whether or not this task's status is **not** empty, meaning it has some `status` character (which may or may not be `\"x\"`) instead of a space in its `[ ]` brackets. |\n| `completed` | Boolean | Whether or not this *specific* task has been completed; this does not consider the completion or non-completion of any child tasks. A task is explicitly considered \"completed\" if it has been marked with an `\"x\"`. If you use a custom status, e.g. `[-]`, `checked` will be true, whereas `completed` will be false. |\n| `fullyCompleted` | Boolean | Whether or not this task and **all** of its subtasks are completed. |\n| `text` | Text | The plain text of this task, including any metadata field annotations. |\n| `visual` | Text | The text of this task, which is rendered by Dataview. This field can be overridden in DataviewJS to allow for different task text to be rendered than the regular task text, while still allowing the task to be checked (since Dataview validation logic normally checks the text against the text in-file). |\n| `line` | Number | The line of the file this task shows up on. |\n| `lineCount` | Number | The number of Markdown lines that this task takes up. |\n| `path` | Text | The full path of the file this task is in. Equals to `file.path` for [pages](./metadata-pages.md). |\n| `section` | Link | Link to the section this task is contained in. |\n| `tags` | List | Any tags inside the task text. |\n| `outlinks` | List | Any links defined in this task. |\n| `link` | Link | Link to the closest linkable block near this task; useful for making links which go to the task. |\n| `children` | List | Any subtasks or sublists of this task. |\n| `task` | Boolean | If true, this is a task; otherwise, it is a regular list element. |\n| `annotated` | Boolean | True if the task text contains any metadata fields, false otherwise. |\n| `parent` | Number | The line number of the task above this task, if present; will be null if this is a root-level task. |\n| `blockId` | Text | The block ID of this task / list element, if one has been defined with the `^blockId` syntax; otherwise null. |\n\nWith usage of the [shorthand syntax](#field-shorthands), following additional properties may be available:\n\n- `completion`: The date a task was completed.\n- `due`: The date a task is due, if it has one.\n- `created`: The date a task was created.\n- `start`: The date a task can be started.\n- `scheduled`: The date a task is scheduled to work on.\n\n### Accessing Implicit Fields in Queries\n\nIf you're using a [TASK](../queries/query-types.md#task) Query, your tasks are the top level information and can be used without any prefix:\n\n~~~markdown\n```dataview\nTASK\nWHERE !fullyCompleted\n```\n~~~\n\nFor every other Query type, you first need to access the implicit field `file.lists` or `file.tasks` to check for these list item specific implicit fields:\n\n~~~markdown\n```dataview\nLIST\nWHERE any(file.tasks, (t) => !t.fullyCompleted)\n```\n~~~\n\nThis will give you back all the file links that have unfinished tasks inside. We get back a list of tasks on page level and thus need to use a [list function](../reference/functions.md) to look at each element.\n"
},
{
"path": "docs/docs/annotation/types-of-metadata.md",
"content": "# Field Types\n\nAll fields in dataview have a **type**, which determines how dataview will render, sort, and operate on that field.\nRead more about how to create fields on [\"Adding metadata\"](add-metadata.md) and which information you have automatically available on [metadata on pages](./metadata-pages.md) and [metadata on tasks and lists](./metadata-tasks.md).\n\n## Why does the type matter?\n\nDataview provides [functions](../reference/functions.md) you can use to modify your metadata and allows you to write all sorts of complex queries. Specific functions need specific data types to work correctly. That means the data type of your field determines which functions you can use on these fields and how the functions behave. Furthermore, depending on the type, the output dataview renders can be different.\n\nMost of the time you do not need to worry too much about the type of your fields, but if you want to perform calculations and other magical operations on your data, you should be aware of them.\n\n!!! example \"Different rendering based on type\"\n If you have this file:\n ~~~yaml\n date1:: 2021-02-26T15:15\n date2:: 2021-04-17 18:00\n\n ```dataview\n TABLE date1, date2\n WHERE file = this.file\n ```\n ~~~\n\n You'll see the following output (depending on your Date + Time Format Setting for dataview): \n\n | File (1) | date1 | date2 |\n | -------- | ----- | ----- |\n | Untitled 2 | 3:15 PM - February 26, 2021 | 2021-04-17 18:00 |\n\n `date1` is recognized as a **Date** while `date2` is a normal **Text** to dataview, that's why `date1` is parsed differently for you. Find out more on [Dates below](#date). \n\n## Available Field Types\n\nDataview knows several field types to cover common use cases.\n\n### Text\n\nThe default catch-all. If a field doesn't match a more specific type, it is plain text.\n\n```markdown\nExample:: This is some normal text.\n```\n\n!!! hint \"Multiline text\"\n Multiline text as a value is only possible via YAML Frontmatter and the pipe operator:\n ```yaml\n ---\n poem: |\n Because I could not stop for Death,\n He kindly stopped for me;\n The carriage held but just ourselves\n And Immortality.\n author: \"[[Emily Dickinson]]\"\n title: \"Because I could not stop for Death\"\n ---\n ```\n For inline fields, a line break means the end of the value. \n\n### Number\n\nNumbers like '6' and '3.6'.\n```markdown\nExample:: 6\nExample:: 2.4\nExample:: -80\n```\n\nIn YAML Frontmatter, you write a number without surrounding quotes: \n\n```yaml\n---\nrating: 8\ndescription: \"A nice little horror movie\"\n---\n```\n\n### Boolean\n\nBoolean only knows two values: true or false, as the programming concept.\n\n```markdown\nExample:: true\nExample:: false\n```\n\n### Date\n\nText that matches the ISO8601 notation will be automatically transformed into a date object. [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) follows the format `YYYY-MM[-DDTHH:mm:ss.nnn+ZZ]`. Everything after the month is optional.\n \n```markdown\nExample:: 2021-04 \nExample:: 2021-04-18\nExample:: 2021-04-18T04:19:35.000\nExample:: 2021-04-18T04:19:35.000+06:30\n```\n\nWhen querying for these dates, you can access properties that give you a certain portion of your date back:\n\n- field.year\n- field.month\n- field.weekyear\n- field.week\n- field.weekday\n- field.day\n- field.hour\n- field.minute\n- field.second\n- field.millisecond\n\nFor example, if you're interested in which month your date lies, you can access it via `datefield.month`:\n\n~~~markdown\nbirthday:: 2001-06-11\n\n```dataview\nLIST birthday\nWHERE birthday.month = date(now).month\n```\n~~~\n\ngives you back all birthdays happening this month. Curious about `date(now)`? Read more about it under [literals](../reference/literals.md#dates).\n\n!!! info \"Displaying of date objects\"\n Dataview renders date objects in a human readable format, i.e. `3:15 PM - February 26, 2021`. You can adjust how this format looks like in Dataview's Setting under \"General\" with \"Date Format\" and \"Date + Time Format\". If you want to adjust the format in a specific query only, use the [dateformat function](../reference/functions.md#dateformatdatedatetime-string).\n\n### Duration\n\nDurations are text of the form ` `, like `6 hours` or `4 minutes`. Common English abbreviations like\n `6hrs` or `2m` are accepted. You can specify multiple units in one field, i.e. `6hr 4min`, optionally with comma separator: `6 hours, 4 minutes`\n\n```markdown\nExample:: 7 hours\nExample:: 16days\nExample:: 4min\nExample:: 6hr7min\nExample:: 9 years, 8 months, 4 days, 16 hours, 2 minutes\nExample:: 9 yrs 8 min\n```\n\nFind the complete list of values that are recognized as a duration on [literals](../reference/literals.md#durations). \n\n!!! hint \"Calculations with dates and durations\"\n Date and Duration types are compatible with each other. This means you can, for example, add durations to a date to produce a new date:\n ~~~markdown\n departure:: 2022-10-07T15:15\n length of travel:: 1 day, 3 hours\n\n **Arrival**: `= this.departure + this.length-of-travel`\n ~~~\n\n and you get back a duration when calculating with dates:\n ~~~markdown\n release-date:: 2023-02-14T12:00\n \n `= this.release-date - date(now)` until release!!\n ~~~\n\n Curious about `date(now)`? Read more about it under [literals](../reference/literals.md#dates).\n\n### Link\n\nObsidian links like `[[Page]]` or `[[Page|Page Display]]`.\n\n```markdown\nExample:: [[A Page]]\nExample:: [[Some Other Page|Render Text]]\n```\n\n!!! info \"Links in YAML Frontmatter\"\n If you reference a link in frontmatter, you need to quote it, as so: `key: \"[[Link]]\"`. This is default Obsidian-supported behavior. Unquoted links lead to a invalid YAML frontmatter that cannot be parsed anymore. \n ```yaml\n ---\n parent: \"[[parentPage]]\"\n ---\n ```\n Please be aware that this is only a link for dataview, but not for Obsidian anymore - that means it won't show up in the outgoing links, won't be displayed on graph view and won't be updated on i.e. a rename.\n\n### List\n\nLists are multi-value fields. In YAML, these are defined as normal YAML lists: \n```yaml\n---\nkey3: [one, two, three]\nkey4:\n - four\n - five\n - six\n---\n```\n\nIn inline fields, they are comma-separated lists values:\n\n```markdown\nExample1:: 1, 2, 3\nExample2:: \"yes\", \"or\", \"no\"\n```\n\nPlease be aware that in Inline fields, you need to wrap **text values into quotes** to be recognized as a list (see `Example2`). `yes, or, no` is recognized as plain text.\n\n!!! info \"Duplicated metadata keys in the same file lead to lists\"\n If you're using a metadata key twice or more in the same note, dataview will collect all values and give you a list. For example\n ~~~markdown\n grocery:: flour\n [...]\n grocery:: soap\n\n ```dataview\n LIST grocery\n WHERE file = this.file\n ```\n ~~~\n will give you a **list** out of `flour` and `soap` back.\n\n!!! hint \"Arrays are lists\"\n In some places of this documentation, you'll read the term \"array\". Array is the term for lists in Javascript - Lists and Arrays are the same. A function that needs an array as argument needs a list as argument.\n\n### Object\n\nObjects are a map of multiple fields under one parent field. These can only be defined in YAML frontmatter, using the YAML object syntax:\n```yaml\n---\nobj:\n key1: \"Val\"\n key2: 3\n key3: \n - \"List1\"\n - \"List2\"\n - \"List3\"\n---\n```\n\n In queries, you can then access these child values via `obj.key1` etc:\n\n~~~markdown\n```dataview\nTABLE obj.key1, obj.key2, obj.key3\nWHERE file = this.file\n```\n~~~\n"
},
{
"path": "docs/docs/api/code-examples.md",
"content": "# Codeblock Examples\n\n## Grouped Books\n\nGroup your books by genre, then create a table for each sorted by rating via a straightforward usage of\nthe dataview rendering API:\n\n```js\nfor (let group of dv.pages(\"#book\").groupBy(p => p.genre)) {\n\tdv.header(3, group.key);\n\tdv.table([\"Name\", \"Time Read\", \"Rating\"],\n\t\tgroup.rows\n\t\t\t.sort(k => k.rating, 'desc')\n\t\t\t.map(k => [k.file.link, k[\"time-read\"], k.rating]))\n}\n```\n\n\n\n## Find All Direct And Indirectly Linked Pages\n\nUse a simple set + stack depth first search to find all notes linked to the current note, or a note of your choosing:\n\n```js\nlet page = dv.current().file.path;\nlet pages = new Set();\n\nlet stack = [page];\nwhile (stack.length > 0) {\n\tlet elem = stack.pop();\n\tlet meta = dv.page(elem);\n\tif (!meta) continue;\n\n\tfor (let inlink of meta.file.inlinks.concat(meta.file.outlinks).array()) {\n\t\tconsole.log(inlink);\n\t\tif (pages.has(inlink.path)) continue;\n\t\tpages.add(inlink.path);\n\t\tstack.push(inlink.path);\n\t}\n}\n\n// Data is now the file metadata for every page that directly OR indirectly links to the current page.\nlet data = dv.array(Array.from(pages)).map(p => dv.page(p));\n```\n"
},
{
"path": "docs/docs/api/code-reference.md",
"content": "# Codeblock Reference\n\nDataview JavaScript Codeblocks are created using the `dataviewjs` language specification for a codeblock:\n\n~~~\n```dataviewjs\ndv.table([], ...)\n```\n~~~\n\nThe API is available through the implicitly provided `dv` (or `dataview`) variable, through which you can query for\ninformation, render HTML, and configure the view.\n\nAsynchronous API calls are marked with `⌛`.\n\n## Query\nQuery methods allow you to query the Dataview index for page metadata; to render this data, use the methods in the [render section](#render).\n\n### `dv.current()`\n\nGet page information (via `dv.page()`) for the page the script is currently executing on.\n\n### `dv.pages(source)`\n\nTake a single string argument, `source`, which is the same form as a [query language source](../reference/sources.md).\nReturn a [data array](data-array.md) of page objects, which are plain objects with all of the page fields as\nvalues.\n\n```js\ndv.pages() => all pages in your vault\ndv.pages(\"#books\") => all pages with tag 'books'\ndv.pages('\"folder\"') => all pages from folder \"folder\"\ndv.pages(\"#yes or -#no\") => all pages with tag #yes, or which DON'T have tag #no\ndv.pages('\"folder\" or #tag') => all pages with tag #tag, or from folder \"folder\"\n```\n\nNote that folders need to be double-quoted inside the string (i.e., `dv.pages(\"folder\")` does not work, but\n`dv.pages('\"folder\"')` does) - this is to exactly match how sources are written in the query language.\n\n### `dv.pagePaths(source)`\n\nAs with `dv.pages`, but just returns a [data array](data-array.md) of paths of pages that match the given source.\n\n```js\ndv.pagePaths(\"#books\") => the paths of pages with tag 'books'\n```\n\n### `dv.page(path)`\n\nMap a simple path or link to the full page object, which includes all of the pages fields. Automatically does link resolution,\nand will figure out the extension automatically if not present.\n\n```js\ndv.page(\"Index\") => The page object for /Index\ndv.page(\"books/The Raisin.md\") => The page object for /books/The Raisin.md\n```\n\n## Render\n\n### `dv.el(element, text)`\n\nRender arbitrary text in the given html element.\n```js\ndv.el(\"b\", \"This is some bold text\");\n```\n\nYou can specify custom classes to add to the element via `cls`, and additional attributes via `attr`:\n\n```js\ndv.el(\"b\", \"This is some text\", { cls: \"dataview dataview-class\", attr: { alt: \"Nice!\" } });\n```\n\n### `dv.header(level, text)`\n\nRender a header of level 1 - 6 with the given text.\n\n```js\ndv.header(1, \"Big!\");\ndv.header(6, \"Tiny\");\n```\n\n### `dv.paragraph(text)`\n\nRender arbitrary text in a paragraph.\n\n```js\ndv.paragraph(\"This is some text\");\n```\n\n### `dv.span(text)`\n\nRender arbitrary text in a span (no padding above/below, unlike a paragraph).\n\n```js\ndv.span(\"This is some text\");\n```\n\n### `dv.execute(source)`\n\nExecute an arbitrary dataview query and embed the view into the current page.\n\n```js\ndv.execute(\"LIST FROM #tag\");\ndv.execute(\"TABLE field1, field2 FROM #thing\");\n```\n\n### `dv.executeJs(source)`\n\nExecute an arbitrary DataviewJS query and embed the view into the current page.\n\n```js\ndv.executeJs(\"dv.list([1, 2, 3])\");\n```\n\n### `dv.view(path, input)`\n\nComplex function which allows for custom views. Will attempt to load a JavaScript file at the given path, passing it\n`dv` and `input` and allowing it to execute. This allows for you to re-use custom view code across multiple pages. Note\nthat this is an asynchronous function since it involves file I/O - make sure to `await` the result!\n\n\n```js\nawait dv.view(\"views/custom\", { arg1: ..., arg2: ... });\n```\n\nIf you want to also include custom CSS in your view, you can instead pass a path to a folder containing `view.js` and\n`view.css`; the CSS will be added to the view automatically:\n\n```\nviews/custom\n -> view.js\n -> view.css\n```\n\nView scripts have access to the `dv` object (the API object), and an `input` object which is exactly whatever the second\nargument of `dv.view()` was.\n\nBear in mind, `dv.view()` cannot read from directories starting with a dot, like `.views`. Example of an incorrect usage:\n\n```js\nawait dv.view(\".views/view1\", { arg1: 'a', arg2: 'b' });\n```\nAttempting this will yield the following exception:\n\n```\nDataview: custom view not found for '.views/view1/view.js' or '.views/view1.js'.\n```\n\nAlso note, directory paths always originate from the vault root.\n\n#### Example\nIn this example, we have a custom script file named `view1.js` in the `scripts` directory. \n\n**File:** `scripts/view1.js`\n```js\nconsole.log(`Loading view1`);\n\nfunction foo(...args) {\n console.log('foo is called with args', ...args);\n}\nfoo(input)\n```\n\nAnd we have an Obsidian document located under `projects`. We'll call `dv.view()` from this document using the `scripts/view1.js` path.\n\n**Document:** `projects/customViews.md`\n```js\nawait dv.view(\"scripts/view1\", { arg1: 'a', arg2: 'b' }) \n```\n\nWhen the above script is executed, it will print the following:\n\n```\nLoading view1\nfoo is called with args {arg1: 'a', arg2: 'b'}\n```\n\n## Dataviews\n\n### `dv.list(elements)`\n\nRender a dataview list of elements; accept both vanilla arrays and data arrays.\n\n```js\ndv.list([1, 2, 3]) => list of 1, 2, 3\ndv.list(dv.pages().file.name) => list of all file names\ndv.list(dv.pages().file.link) => list of all file links\ndv.list(dv.pages(\"#book\").where(p => p.rating > 7)) => list of all books with rating greater than 7\n```\n\n### `dv.taskList(tasks, groupByFile)`\n\nRender a dataview list of `Task` objects, as obtained by `page.file.tasks`. By default, this view will automatically\ngroup the tasks by their origin file. If you provide `false` as a second argument explicitly, it will instead render them\nas a single unified list.\n\n```js\n// List all tasks from pages marked '#project'\ndv.taskList(dv.pages(\"#project\").file.tasks)\n\n// List all *uncompleted* tasks from pages marked #project\ndv.taskList(dv.pages(\"#project\").file.tasks\n .where(t => !t.completed))\n\n// List all tasks tagged with '#tag' from pages marked #project\ndv.taskList(dv.pages(\"#project\").file.tasks\n .where(t => t.text.includes(\"#tag\")))\n\n// List all tasks from pages marked '#project', without grouping.\ndv.taskList(dv.pages(\"#project\").file.tasks, false)\n```\n\n### `dv.table(headers, elements)`\n\nRenders a dataview table. `headers` is an array of column headers. `elements` is an array of rows. Each row is itself an array of columns. Inside a row, every column which is an array will be rendered with bullet points.\n\n```js\ndv.table(\n\t[\"Col1\", \"Col2\", \"Col3\"],\n\t\t[\n\t\t\t[\"Row1\", \"Dummy\", \"Dummy\"],\n\t\t\t[\"Row2\", \n\t\t\t\t[\"Bullet1\",\n\t\t\t\t \"Bullet2\",\n\t\t\t\t \"Bullet3\"],\n\t\t\t \"Dummy\"],\n\t\t\t[\"Row3\", \"Dummy\", \"Dummy\"]\n\t\t]\n\t);\n```\n\nAn example of how to render a simple table of book info sorted by rating.\n\n```js\ndv.table([\"File\", \"Genre\", \"Time Read\", \"Rating\"], dv.pages(\"#book\")\n .sort(b => b.rating)\n .map(b => [b.file.link, b.genre, b[\"time-read\"], b.rating]))\n```\n\n## Markdown Dataviews\n\nFunctions which render to plain Markdown strings which you can then render or manipulate as desired.\n\n### `dv.markdownTable(headers, values)`\n\nEquivalent to `dv.table()`, which renders a table with the given list of headers and 2D array of elements, but\nreturns plain Markdown.\n\n```js\n// Render a simple table of book info sorted by rating.\nconst table = dv.markdownTable([\"File\", \"Genre\", \"Time Read\", \"Rating\"], dv.pages(\"#book\")\n .sort(b => b.rating)\n .map(b => [b.file.link, b.genre, b[\"time-read\"], b.rating]))\n\ndv.paragraph(table);\n```\n\n### `dv.markdownList(values)`\n\nEquivalent to `dv.list()`, which renders a list of the given elements, but returns plain Markdown.\n\n```js\nconst markdown = dv.markdownList([1, 2, 3]);\ndv.paragraph(markdown);\n```\n\n### `dv.markdownTaskList(tasks)`\n\nEquivalent to `dv.taskList()`, which renders a task list, but returns plain Markdown.\n\n```js\nconst markdown = dv.markdownTaskList(dv.pages(\"#project\").file.tasks);\ndv.paragraph(markdown);\n```\n \n## Utility\n\n### `dv.array(value)`\n\nConvert a given value or array into a Dataview [data array](data-array.md). If the value is already a data array, returns\nit unchanged.\n\n```js\ndv.array([1, 2, 3]) => dataview data array [1, 2, 3]\n```\n\n### `dv.isArray(value)`\n\nReturns true if the given value is an array or dataview array.\n\n```js\ndv.isArray(dv.array([1, 2, 3])) => true\ndv.isArray([1, 2, 3]) => true\ndv.isArray({ x: 1 }) => false\n```\n\n### `dv.fileLink(path, [embed?], [display-name])`\n\nConverts a textual path into a Dataview `Link` object; you can optionally also specify if the link is embedded as well\nas it's display name.\n\n```js\ndv.fileLink(\"2021-08-08\") => link to file named \"2021-08-08\"\ndv.fileLink(\"book/The Raisin\", true) => embed link to \"The Raisin\"\ndv.fileLink(\"Test\", false, \"Test File\") => link to file \"Test\" with display name \"Test File\"\n```\n\n### `dv.sectionLink(path, section, [embed?], [display?])`\n\nConverts a textual path + section name into a Dataview `Link` object; you can optionally also specify if the link is embedded and\nit's display name.\n\n```js\ndv.sectionLink(\"Index\", \"Books\") => [[Index#Books]]\ndv.sectionLink(\"Index\", \"Books\", false, \"My Books\") => [[Index#Books|My Books]]\n```\n\n### `dv.blockLink(path, blockId, [embed?], [display?])`\n\nConverts a textual path + block ID into a Dataview `Link` object; you\ncan optionally also specify if the link is embedded and it's display name.\n\n```js\ndv.blockLink(\"Notes\", \"12gdhjg3\") => [[Index#^12gdhjg3]]\n```\n\n### `dv.date(text)`\n\nCoerce text and links to luxon `DateTime`; if provided with a `DateTime`, return it unchanged.\n\n```js\ndv.date(\"2021-08-08\") => DateTime for August 8th, 2021\ndv.date(dv.fileLink(\"2021-08-07\")) => dateTime for August 8th, 2021\n```\n\n### `dv.duration(text)`\n\nCoerce text to a luxon `Duration`; uses the same parsing rules as Dataview duration types.\n\n```js\ndv.duration(\"8 minutes\") => Duration { 8 minutes }\ndv.duration(\"9 hours, 2 minutes, 3 seconds\") => Duration { 9 hours, 2 minutes, 3 seconds }\n```\n\n### `dv.compare(a, b)`\n\nCompare two arbitrary JavaScript values according to dataview's default comparison rules; useful if you are writing a\ncustom comparator and want to fall back to the default behavior. Returns a negative value if `a < b`, 0 if `a = b`, and\na positive value if `a > b`.\n\n```js\ndv.compare(1, 2) = -1\ndv.compare(\"yes\", \"no\") = 1\ndv.compare({ what: 0 }, { what: 0 }) = 0\n```\n\n### `dv.equal(a, b)`\n\nCompare two arbitrary JavaScript values and return true if they are equal according to Dataview's default comparison\nrules.\n\n```js\ndv.equal(1, 2) = false\ndv.equal(1, 1) = true\n```\n\n### `dv.clone(value)`\n\nDeep clone any Dataview value, including dates, arrays, and links.\n\n```js\ndv.clone(1) = 1\ndv.clone({ a: 1 }) = { a: 1 }\n```\n\n### `dv.parse(value)`\n\nParse an arbitrary string object into a complex Dataview type\n(mainly supporting links, dates, and durations).\n\n```js\ndv.parse(\"[[A]]\") = Link { path: A }\ndv.parse(\"2020-08-14\") = DateTime { 2020-08-14 }\ndv.parse(\"9 seconds\") = Duration { 9 seconds }\n```\n\n## File I/O\n\nThese utility methods are all contained in the `dv.io` sub-API, and are all *asynchronous* (marked by ⌛).\n\n### ⌛ `dv.io.csv(path, [origin-file])`\n\nLoad a CSV from the given path (a link or string). Relative paths will be resolved relative to the optional origin file (defaulting to the current file if not provided). Return a dataview array, each element containing an object of the CSV values; if the file does not exist, return `undefined`.\n\n```js\nawait dv.io.csv(\"hello.csv\") => [{ column1: ..., column2: ...}, ...]\n```\n\n### ⌛ `dv.io.load(path, [origin-file])`\n\nLoad the contents of the given path (a link or string) asynchronously. Relative paths will be resolved relative to the\noptional origin file (defaulting to the current file if not provided). Returns the string contents of the file, or\n`undefined` if the file does not exist.\n\n```js\nawait dv.io.load(\"File\") => \"# File\\nThis is an example file...\"\n```\n\n### `dv.io.normalize(path, [origin-file])`\n\nConvert a relative link or path into an absolute path. If `origin-file` is provided, then the resolution is doing as if\nyou were resolving the link from that file; if not, the path is resolved relative to the current file.\n\n```js\ndv.io.normalize(\"Test\") => \"dataview/test/Test.md\", if inside \"dataview/test\"\ndv.io.normalize(\"Test\", \"dataview/test2/Index.md\") => \"dataview/test2/Test.md\", irrespective of the current file\n```\n\n## Query Evaluation\n\n### ⌛ `dv.query(source, [file, settings])`\n\nExecute a Dataview query and return the results as a structured return.\nThe return type of this function varies by the query type being executed,\nthough will always be an object with a `type` denoting the return type. This version of `query` returns a result type - you may want `tryQuery`, which instead throws an error on failed query execution.\n\n```javascript\nawait dv.query(\"LIST FROM #tag\") =>\n { successful: true, value: { type: \"list\", values: [value1, value2, ...] } }\n\nawait dv.query(`TABLE WITHOUT ID file.name, value FROM \"path\"`) =>\n { successful: true, value: { type: \"table\", headers: [\"file.name\", \"value\"], values: [[\"A\", 1], [\"B\", 2]] } }\n\nawait dv.query(\"TASK WHERE due\") =>\n { successful: true, value: { type: \"task\", values: [task1, task2, ...] } }\n```\n\n`dv.query` accepts two additional, optional arguments:\n1. `file`: The file path to resolve the query from (in case of references to `this`). Defaults to the current file.\n2. `settings`: Execution settings for running the query. This is largely an advanced use case (where I recommend you\n directly check the API implementation to see all available options).\n\n### ⌛ `dv.tryQuery(source, [file, settings])`\n\nExactly the same as `dv.query`, but more convenient in short scripts as\nexecution failures will be raised as JavaScript exceptions instead of a\nresult type.\n\n### ⌛ `dv.queryMarkdown(source, [file], [settings])`\n\nEquivalent to `dv.query()`, but returns rendered Markdown.\n\n```js\nawait dv.queryMarkdown(\"LIST FROM #tag\") =>\n { successful: true, value: { \"- [[Page 1]]\\n- [[Page 2]]\" } }\n```\n\n### ⌛ `dv.tryQueryMarkdown(source, [file], [settings])`\n\nExactly the same as `dv.queryMarkdown()`, but throws an error on parse failure.\n\n### `dv.tryEvaluate(expression, [context])`\n\nEvaluate an arbitrary dataview expression (like `2 + 2` or `link(\"text\")` or `x * 9`); throws an `Error` on parse or\nevaluation failure. `this` is an always-available implicit variable which refers to the current file.\n\n```js\ndv.tryEvaluate(\"2 + 2\") => 4\ndv.tryEvaluate(\"x + 2\", {x: 3}) => 5\ndv.tryEvaluate(\"length(this.file.tasks)\") => number of tasks in the current file\n```\n\n### `dv.evaluate(expression, [context])`\n\nEvaluate an arbitrary dataview expression (like `2 + 2` or `link(\"text\")` or `x * 9`), returning a `Result` object of\nthe result. You can unwrap the result type by checking `result.successful` (and then fetching either `result.value`\nor `result.error`). If you want a simpler API that throws an error on a failed evaluation, use `dv.tryEvaluate`.\n\n```js\ndv.evaluate(\"2 + 2\") => Successful { value: 4 }\ndv.evaluate(\"2 +\") => Failure { error: \"Failed to parse ... \" }\n```\n"
},
{
"path": "docs/docs/api/data-array.md",
"content": "# Data Arrays\n\nThe general representation of result lists in Dataview is the `DataArray`, which is a [proxied](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) version of the JavaScript array with expanded\nfunctionality. Data arrays support indexing and iteration (via `for` and `for ... of` loops), like normal arrays do, but\nalso include many data manipulation operators like `sort`, `groupBy`, `distinct`, `where`, and so on to make\nmanipulating tabular data easier.\n\n## Creation\n\nData arrays are returned by most Dataview APIs that can return multiple results, such as `dv.pages()`. You can also\nexplicitly convert a normal JavaScript array into a Dataview array using `dv.array()`. If you want to convert a\nData array back to a normal array, use `DataArray#array()`.\n\n## Indexing and Swizzling\n\nData arrays support regular indexing just like normal arrays (like `array[0]`), but importantly, they also support\nquery-language-style \"swizzling\": if you index into a data array with a field name (like `array.field`), it\nautomatically maps every element in the array to `field`, flattening `field` if it itself is also an array.\n\nFor example, `dv.pages().file.name` will return a data array of all file names in your vault;\n`dv.pages(\"#books\").genres` will return a flattened list of all genres in your books.\n\n## Raw Interface\n\nThe full interface for the data array implementation is provided below for reference:\n\n```ts\n/** A function which maps an array element to some value. */\nexport type ArrayFunc = (elem: T, index: number, arr: T[]) => O;\n\n/** A function which compares two types. */\nexport type ArrayComparator = (a: T, b: T) => number;\n\n/**\n * Proxied interface which allows manipulating array-based data. All functions on a data array produce a NEW array\n * (i.e., the arrays are immutable).\n */\nexport interface DataArray {\n /** The total number of elements in the array. */\n length: number;\n\n /** Filter the data array down to just elements which match the given predicate. */\n where(predicate: ArrayFunc): DataArray;\n /** Alias for 'where' for people who want array semantics. */\n filter(predicate: ArrayFunc): DataArray;\n\n /** Map elements in the data array by applying a function to each. */\n map(f: ArrayFunc): DataArray;\n /** Map elements in the data array by applying a function to each, then flatten the results to produce a new array. */\n flatMap(f: ArrayFunc): DataArray;\n /** Mutably change each value in the array, returning the same array which you can further chain off of. */\n mutate(f: ArrayFunc): DataArray;\n\n /** Limit the total number of entries in the array to the given value. */\n limit(count: number): DataArray;\n /**\n * Take a slice of the array. If `start` is undefined, it is assumed to be 0; if `end` is undefined, it is assumed\n * to be the end of the array.\n */\n slice(start?: number, end?: number): DataArray;\n /** Concatenate the values in this data array with those of another iterable / data array / array. */\n concat(other: Iterable): DataArray;\n\n /** Return the first index of the given (optionally starting the search) */\n indexOf(element: T, fromIndex?: number): number;\n /** Return the first element that satisfies the given predicate. */\n find(pred: ArrayFunc): T | undefined;\n /** Find the index of the first element that satisfies the given predicate. Returns -1 if nothing was found. */\n findIndex(pred: ArrayFunc, fromIndex?: number): number;\n /** Returns true if the array contains the given element, and false otherwise. */\n includes(element: T): boolean;\n\n /**\n * Return a string obtained by converting each element in the array to a string, and joining it with the\n * given separator (which defaults to ', ').\n */\n join(sep?: string): string;\n\n /**\n * Return a sorted array sorted by the given key; an optional comparator can be provided, which will\n * be used to compare the keys in lieu of the default dataview comparator.\n */\n sort(key: ArrayFunc, direction?: \"asc\" | \"desc\", comparator?: ArrayComparator): DataArray;\n\n /**\n * Return an array where elements are grouped by the given key; the resulting array will have objects of the form\n * { key: , rows: DataArray }.\n */\n groupBy(key: ArrayFunc, comparator?: ArrayComparator): DataArray<{ key: U; rows: DataArray }>;\n\n /**\n * Return distinct entries. If a key is provided, then rows with distinct keys are returned.\n */\n distinct(key?: ArrayFunc, comparator?: ArrayComparator): DataArray;\n\n /** Return true if the predicate is true for all values. */\n every(f: ArrayFunc): boolean;\n /** Return true if the predicate is true for at least one value. */\n some(f: ArrayFunc): boolean;\n /** Return true if the predicate is FALSE for all values. */\n none(f: ArrayFunc): boolean;\n\n /** Return the first element in the data array. Returns undefined if the array is empty. */\n first(): T;\n /** Return the last element in the data array. Returns undefined if the array is empty. */\n last(): T;\n\n /** Map every element in this data array to the given key, and then flatten it.*/\n to(key: string): DataArray;\n /**\n * Recursively expand the given key, flattening a tree structure based on the key into a flat array. Useful for handling\n * hierarchical data like tasks with 'subtasks'.\n */\n expand(key: string): DataArray;\n\n /** Run a lambda on each element in the array. */\n forEach(f: ArrayFunc): void;\n\n /** Calculate the sum of the elements in the array. */\n sum(): number;\n\n /** Calculate the average of the elements in the array. */\n avg(): number;\n\n /** Calculate the minimum of the elements in the array. */\n min(): number;\n\n /** Calculate the maximum of the elements in the array. */\n max(): number;\n\n /** Convert this to a plain javascript array. */\n array(): T[];\n\n /** Allow iterating directly over the array. */\n [Symbol.iterator](): Iterator;\n\n /** Map indexes to values. */\n [index: number]: any;\n /** Automatic flattening of fields. Equivalent to implicitly calling `array.to(\"field\")` */\n [field: string]: any;\n}\n```\n"
},
{
"path": "docs/docs/api/intro.md",
"content": "# Overview\n\nThe Dataview JavaScript API allows for executing arbitrary JavaScript with access to the dataview indices and query\nengine, which is good for complex views or interop with other plugins. The API comes in two flavors: plugin facing, and\nuser facing (or 'inline API usage').\n\n## Inline Access\n\nYou can create a \"DataviewJS\" block via:\n\n~~~\n```dataviewjs\ndv.pages(\"#thing\")...\n```\n~~~\n\nCode executed in such codeblocks have access to the `dv` variable, which provides the entirety of the codeblock-relevant\ndataview API (like `dv.table()`, `dv.pages()`, and so on). For more information, check out the [codeblock API\nreference](code-reference.md).\n\n## Plugin Access\n\nYou can access the Dataview Plugin API (from other plugins or the console) through `app.plugins.plugins.dataview.api`;\nthis API is similar to the codeblock reference, with slightly different arguments due to the lack of an implicit file\nto execute the queries in. For more information, check out the [Plugin API reference](code-reference.md).\n"
},
{
"path": "docs/docs/changelog.md",
"content": "# 0.5.70 (Beta)\n\nStill attempting to fix #2557, github is acting up.\n\n\n---\n\n# 0.5.69 (Beta)\n\nAttempting to fix #2557, but uncertain to any side effects.\n\n\n---\n\n# 0.5.68\n\n- Many fixes to the documentation\n- #2318 & co: Various fixes related to _live preview_ rendering of lists\n- New/documented functions for `unique()`, `display()`, `firstvalue()`\n- Added DOM information related to standalone inline fields\n\nThis is the first release done by @holroy, so thanks to him for further developing of _Dataview_. Thank you also to all the people having contributed through PRs and issues.\n\n---\n\n# 0.5.67\n\nIncludes several documentation fixes and several community-contributed bug fixes.\n\n- @reply2za: Fixed inline rendering in the reading view.\n- @carlesalbasboix: Adds sum(), avg(), min(), and max() to data arrays.\n- @mnaoumov: Adds code mirror configuration which code highlights dataviewjs!\n\n---\n\n# 0.5.66\n\nBugfix for version comparisons to fix some other plugins having broken interactions with Dataview.\n\n---\n\n# 0.5.65\n\nA maintenance update which fixes some issues with rendering embeds in Dataviews and adds a few new functions.\n\n- Adds the `hash()` function for generating consistent uniformly-distributed values given arbitrary inputs. Primarily useful for creating \"random\" views which remain consistent across page refreshes. Thanks to @holroy.\n- Adds the `slice()` function for slicing arrays, similar to Javascript's `Array.slice`. Thanks to @holroy.\n- Fixes several issues with rendering embeds inside dataviews. Thanks to @GottZ.\n- Several documentation improvements around tasks - thanks to @holroy and @RaviOnline.\n\n---\n\n# 0.5.64\n\nMore bug fixes for inline field rendering.\n\n\n---\n\n# 0.5.63\n\n- More bugfixes from @RyotaUshio for rendering Markdown paragraphs and other blocks in DataviewJS.\n\n---\n\n# 0.5.62\n\nSeveral more inline field fixes from @RyotaUshio, including more configuration options, fixing inline fields being rendered inside codeblocks, and more. Thanks!\n\n---\n\n# 0.5.61\n\n- @RyotaUshio: Fix several bugs related to the new inline field rendering, including source mode and fixing date formatting.\n\n---\n\n# 0.5.60\n\n- @RyotaUshio: Add explicit rendering of inline fields in live preview. They are much more visually distinct now!\n- @MarioRicalde: Adds `PluginApi#evaluateInline(expression, path)` to the plugin API, which evaluate expressions as if you were on the given page.\n\n---\n\n# 0.5.59\n\n- Fix an issue with the plugin failing to run on iOS due to an esoteric regex issue.\n\n---\n\n# 0.5.58\n\n- Negative durations will now be properly rendered.\n\n---\n\n# 0.5.57\n\nMaintenance patch which bumps many internal dependency versions and which includes approximately ~20 community-contributed PRs which add some new functions, fix some Dataview interactions with properties, and more!\n\n---\n\n# Unreleased\n\n- DQL: Adds new `durationformat(duration, string)` function.\n- DQL: New math rounding functions, `trunc(number)`, `floor(number)`, `ceil(number)`.\n\n# 0.5.56\n\n- Includes some performance fixes on recent versions of Obsidian 1.3+ due to some API changes. Thanks @kometenstaub.\n- Documentation cleanups and improvements by @mocsa, @protofarer, @seanlzx, and @somidad.\n- Adds the new `flat(array)` method for flattening nested arrays, as well as parsing dates using arbitrary formats using\n `date(text, \"format\")`. Thanks @holroy!\n\n---\n\n# 0.5.55\n\n- Durations are now internationalized using luxon's new internationalization support.\n- Dataviews should now properly render inside Canvas and some other contexts. Thanks @GamerGirlandCo!\n\n---\n\n# 0.5.54\n\n- Regular list items are now also clickable in task views, not just task lines! Thanks to @LilaRest.\n\n---\n\n# 0.5.53\n\n- Fix some documentation issues causing docs to not be updated.\n\n---\n\n# 0.5.52\n\nSubstantial documentation improvements thanks to @s-blu and @AB1908!\n\n- For people concerned about dataviewjs code execution from copy-pasting, @eyuelt has made it possible to change the\n dataviewjs codeblock prefix.\n- @sohanglal has added some documentation for `task.visual` for changing the visual text of a task.\n- @Chouffy and @Daryl-Horton have fixed some bad documentation links!\n- @vrtmrz swapped the regex used for parsing tags to better match Obsidian's own parser.\n- @alexfertel has added `regextest`, which allows for matching parts of a string instead of the whole thing.\n- @iamrecursion has added more metadata to file links, so they now include section metadata. This may cause some slight\n visual changes in link views.\n\n---\n\n# 0.5.51 (Beta)\n\n- Allow disabling regular Dataview inline queries via configuration option.\n\n---\n\n# 0.5.50 (Beta)\n\n- Expose dataview EXPRESSION and QUERY parsing to the dataview npm plugin, so others can parse dataview ASTs.\n- Fix documentation issue with `join`.\n\n---\n\n# 0.5.49 (Beta)\n\n- Add the `average` function to compute averages of lists (`average([list of things])`).\n- Added documentation for `average`, `min`, `max`, `minby`, and `maxby` functions.\n- Fixed the broken `nonnull` function and documented it.\n\n---\n\n# 0.5.48 (Beta)\n\nWe're back to more regular beta releases while I trial out new functionality!\n\n- Fixed broken list behavior for `dv.markdownTaskList`.\n- @GamerGirlandCo: Better handling of block IDs when checking off tasks!\n- @s-blu and @AB1908: Lots of big documentation upgrades! Nice!\n- @leoccyao: More block ID task checking fixes. Should work after this one.\n- Add expression/query parsing to the dataview NPM package.\n- @charleshan: Fix a missing header level in the dataview `dv.header` example.\n\n---\n\n# 0.5.47\n\nImproves `date + duration` behavior when either the date or duration are null.\n\n---\n\n# 0.5.46\n\n- Fix #1412: Fix bad `file.cday` and `file.ctime` comparisons due to wrong timezone being set. Ugh.\n\n---\n\n# 0.5.45\n\n- #1400: Properly use the group by field for the group name.\n- Fix bad table highlighting in some themes.\n\n---\n\n# 0.5.44\n\n- #1404: Fixed dates in non-local timezones parsing incorrectly.\n- Fixed some build non-determinism issues.\n- Swapped to pull requests for adding new functionality, and added some more internal tests.\n\n---\n\n# 0.5.43\n\n- Fix #1366: Better handling of calendar emoji (used as due dates in tasks).\n\n---\n\n# 0.5.42\n\nIt's been over a month since the last release! Anyway, this release bundles several nice user-contributed features:\n\n- @AB1908: Tag queries are now case insensitive.\n- @AB1908: Shift-clicking a link/task to open in a new tab now works properly on Mac.\n- @AB1908: Numerous documentation fixes for clarity and more examples.\n- @AnnaKornfeldSimpson: Additional emoji shorthands for more task fields (finished, due).\n- @ooker777: Documentation improvements for some DataviewJS functions, and the ability to use inline emoji for the\n completion tracking feature.\n- @mt-krainski: Custom date formats for task completions.\n- @gentlegiantJGC: Better support for nested inline fields (i.e., less crashy).\n\n---\n\n# 0.5.41\n\n- Fix a bad regex doing escaping in markdown tables.\n- Improve async documentation.\n\n---\n\n# 0.5.40\n\nAdds some more documentation about the new markdown functionality.\n\n---\n\n# 0.5.39\n\n- Fixed an issue where checking a task in a task view would check the wrong box visually.\n- Added experimental plugin APIs for querying dataview directly as markdown, and converting dataview results to properly\n formatted markdown.\n\n---\n\n# 0.5.38\n\n- Some minor documentation improvements.\n- Fix an issue with inline fields rendering out of order. That was a weird bug.\n\n---\n\n# 0.5.37\n\nFixes inline field rendering to once again work for highlighting/links, as well as some other rendering quirks with\ninline queries in codeblocks.\n\n---\n\n# 0.5.36\n\n- Fix a bug when checking if an element is an HTMLElement.\n- Properly include the nice improvements to the file count in tables and lists.\n\n---\n\n# 0.5.35\n\n- Fix #1196, #1176: Re-enable HTML values. This was never a featured I advertised since it was just for some internal\n hackery, but it appears people just discovered it in DataviewJS queries.\n- Improved initial time to popular queries that use `file.starred`.\n\n---\n\n# 0.5.34\n\n- Fix #1174: Fix indexing with a variable.\n- Fix an issue with the experimental calendar view.\n\n---\n\n# 0.5.33\n\n- Fix a bug with inline views that was introduced in 0.5.32.\n\n---\n\n# 0.5.32\n\nThe Dataview API has been noticeably revamped - there are now approximately twice as many functions available on the\nplugin API as there were before, and some additional utilities have been added to both the plugin and inline API. I\nwill be finishing up the associated new \"extension\" functionality shortly, which will allow:\n\n1. For custom Dataview + DataviewJS functions to be added via plugins.\n2. For custom renderable objects (progress bars, embedded task lists, embedded tables) to be added to any Dataview view via plugins.\n3. For plugins to provide alternative behavior for some dataview functionality (such as integrating task plugins with\n the dataview task query).\n \nAs part of the API revamp, it is now possible to programmatically execute Dataview and DataviewJS queries - either for\nusing the existing Dataview query language in your own plugin, or for embedding dataview. The Dataview npm library also\nnow exposes many useful internal Dataview types, including the AST structure for all dataview queries.\n\nI am hoping that cleaning up the Dataview API and making it much more extensible will allow for Dataview [to](to) integrate\nmuch better with existing plugins, and to provide the full power of the in-memory index for plugins. I have been very\ncarefully watching index performance in recent weeks to ensure smooth frontend performance for anyone using the API\n(with a goal of <10ms for most queries).\n\n---\n\n# 0.5.31\n\nTasks now have an `outlinks` list field which includes all links in the task; this can be used for finding tasks with\nlinks in them.\n\n---\n\n# 0.5.30\n\n- Added the `typeof(any)` function in Dataview, which obtains the type of any value for comparison:\n```javascript\ntypeof(\"text\") = \"string\"\ntypeof(1) = \"number\"\ntypeof([1, 2, 3]) = \"array\"\n```\n\n- Added the modulo operator (`%`) for doing integer division remainder. I.e., `14 % 2 = 0` and `14 % 3 = 2`.\n- Fixed some minor spacing issues with lists in tables.\n\n---\n\n# 0.5.29\n\nFix another subtle incompatibility between 0.4.26 and 0.5.29 - if you frequently used empty inline fields (like\n`Key::` with no value), the 0.5+ behavior is now the same as 0.4 behavior and will map such fields to null instead of an\nempty string.\n\nThis may fix a broad variety of \"subtly wrong\" queries that you may have seen after the upgrade.\n\n---\n\n# 0.5.28\n\n- Fix a bug with some more string concatenations and null handling.\n\n---\n\n# 0.5.27\n\nMore performance + correctness bugfixes.\n\n- The parser has been made a little more robust to prevent major indexing issues (or at least recover from them\n quickly).\n- Several new strange tag variants are now supported.\n- Markdown links are now properly indexed again.\n\nSome DataviewJS performance issues should be resolved now, especially for external plugins using Dataview. This fix\ndoes involve a slight API break w.r.t. what types are wrapped into Dataview Arrays (which provide functions like\n`.where()`). Generally, only Dataview-provided implicits are wrapped in data arrays now; frontmatter and inline fields\nare always now regular JS arrays - use `dv.array()` to explicitly make a data array if you want the advanced querying.\n\n---\n\n# 0.5.26\n\nMore small bugfixes:\n\n- Fix a few small link rendering issues.\n- Tag extraction from tasks now handles punctuation properly.\n- Upgrade luxon (which is embedded in DataviewJS) to 2.4.0.\n\n---\n\n# 0.5.25\n\n- Fix #1147: Fix there being a `#null` tag for files with an empty `tag` or `tags` frontmatter.\n\n---\n\n# 0.5.24\n\nSeveral bugfixes:\n\n- Nulls are now sorted first rather than last; it's generally good practice to explicitly check for nulls in your\n queries to avoid strange behavior.\n- Dataview now properly parses space-delimited tags (like `tags: abc def ghi`).\n- Dataview now supports dropping the entire file cache in case of bugs.\n\n---\n\n# 0.5.23\n\n- Fix #1140: Force API objects to be arrays if they are iterables.\n\n---\n\n# 0.5.22\n\n- Fix #1135: Use 'x' instead of 'X' for checkboxes.\n\n---\n\n# 0.5.21\n\nA long-overdue swap from the beta branch to the stable branch. The beta branch should not include any (intended) breaking\nchanges, and has some nice performance improvements that come along with it! Here are the major changes:\n\n- Most views now use React and no longer flicker when updating; this is not the case yet for DataviewJS, which will be\n getting equivalent treatment in the future.\n- Dataview now caches metadata, so Dataview loads are very fast after the first time you open your vault. Dataview still\n needs to visit every file when you update the plugin version, so that should be the only times you experience slower\n load times.\n- A brand new task view backend and query which allows you to filter per-task, rather than per-page! Check the\n documentation for details, but this broadly means `WHERE` statements now use task properties instead of page\n properties.\n- Some additional metadata is now available for use - `file.starred`, `file.lists`, and more metadata in\n `file.tasks`.\n\nThere have been some moderate documentation touch-ups to keep things up to date; I'm still working on a walkthrough for\ncommon Dataview use cases. This review also includes about ~30-40 bugfixes; some new bugs may arise due to internal\nchanges, so please flag them if you encounter them.\n\n---\n\n# 0.5.20 (Beta)\n\nSlight fix to hopefully improve some strange reported cases of bad indexing at startup.\n\n---\n\n# 0.5.19 (Beta)\n\nDataview now uses IndexedDB to cache file metadata, reducing startup time to virtually nothing if you've opened the\nvault before; if you have a small vault (<1000 notes), you may notice a slight improvement, but large vaults and mobile\ndevices will notice a very significant performance improvement to \"first valid paint\". Some other performance parameters\nhave been tuned to hopefully make the default experience better.\n\nA few small bugs related to rendering have also been squashed, including an issue with images being scaled wrongly.\n\n---\n\n# 0.5.18 (Beta)\n\n- Tasks in task views now support alternative task status characters like '!' and '/'; thanks @ebullient.\n- A few documentation nit fixes.\n- Added `DataArray#sortInPlace` for a more efficient mutable sort for niche use cases.\n\n---\n\n# 0.5.17 (Beta)\n\n- Improved behavior when clicking on tasks in the task view; will now properly scroll to the relevant line in long\n files!\n- Fixed a bug with incorrect counts being displayed in task views.\n- Added `tags` as a field available on task items, so you can now do things like `TASK WHERE contains(tags, \"#tag\")`.\n\n---\n\n# 0.5.16 (Beta)\n\nDataview now tracks initialization and will report when all files have been indexed in the console; you can\nprogrammatically see this via `dataview:index-ready`, or by checking `api.index.initialized`.\n\n---\n\n# 0.5.15 (Beta)\n\n- Add hover highlights to tables to make seeing rows a little easier.\n- Tables and task lists now include counts of the number of results in the headers.\n- Further improved task selection in the task view.\n\n---\n\n# 0.5.14 (Beta)\n\n- Fix task highlighting when not grouping.\n- Remove some spurious console logging.\n- Slightly improve task highlighting behavior when clicking on a task.\n\n---\n\n# 0.5.13 (Beta)\n\nSeveral smaller bugfixes!\n\n- Fix #997: Use the group by field name in the table name.\n- Prevent tons of errors if you incorrectly set the inline query prefix.\n\n---\n\n# 0.5.12 (Beta)\n\nImprove error messages for queries somewhat and get rid of some ugly output.\n\n---\n\n# 0.5.11 (Beta)\n\nAdd detection of tasks inside of block quotes, as well as correctly implement automatic checking and unchecking of these\ntasks.\n\n---\n\n# 0.5.10 (Beta)\n\nAdds the `Dataview: Force Refresh Views` Command (accessible via the Ctrl+P command view) to force current views to\nrefresh immediately.\n\n---\n\n# 0.5.9 (Beta)\n\nAnother fix for due-date related emoji in tasks. I hate emoji.\n\n---\n\n# 0.5.8 (Beta)\n\nFix some issues with infinite loops of tasks due to bad Obsidian metadata (potentially due to being out of date?).\n\n---\n\n# 0.5.7 (Beta)\n\nFix issues with parsing '🗓️2021-08-29' due-date annotations on tasks, as well as an issue with properly extracting\ndue/completed/completed times for use in queries.\n\n---\n\n# 0.5.6 (Beta)\n\nProper release of 0.5.5 plus one additional small improvement:\n\n- Add `duration * number` and `duration / number` operations for manipulation durations numerically.\n\n---\n\n# 0.5.5 (Beta)\n\nMore small features:\n\n- Fix issues with task sorting not doing anything. Sort away!\n- Table headers can now be arbitrary markdown. So you can put things like links in your headers: `TABLE (1 + 2) AS\n \"[[File]]\".\n- You can now specify the size of an image embed by providing WxH in it's display property: `![[image.png|50x50]]`.\n\n---\n\n# 0.5.4 (Beta)\n\nImproved image rendering for some link types, and adds the `embed(link)` and `embed(link, false)` options to convert\nlinks to/from their embedded equivalents.\n\n---\n\n# 0.5.3 (Beta)\n\nIterative beta which adds a few nice QoL features and fixes some more bugs:\n\n- Internally swapped to a React-based renderer; this should not have a noticeable perf or usability impact, but makes it\n easier for me to implement complex table/list behaviors.\n- Naming your fields with `AS \"Name\"` is now optional; Dataview will infer the name from the expression automatically.\n For example, `TABLE 8 + 4, 3 + 6 FROM ...` is now a valid table expression, and the columns will be named `8 + 4` and\n `3 + 6` respectively.\n- Some issues with array and object rendering were corrected.\n- Error messages on empty dataview results were improved and now show up for all views.\n\nInline images are now rendered correctly in Dataview tables and lists - no more hacky `app://local/` shenanigans!\n\n---\n\n# 0.5.2 (Beta)\n\n- Fix #971: Objects now work properly inside DataviewQL evaluation.\n\n---\n\n# 0.5.1 (Beta)\n\n- Temporarily revert the new task metadata behavior: inline fields in sublists of tasks are added to the page, instead\n of the task. This behavior is not good, but is compatible with legacy usages of task metadata, which should not break\n some existing queries.\n - This behavior will be removed in the future behind a flag.\n- Added the 'visual' field to tasks - if set, tasks render 'visual' instead of their regular text.\n- Fixed `DataArray#mutate()`.\n\n---\n\n# 0.5.0 (Beta)\n\nRe-release of broken release 0.4.23, now hopefully with fixes that make it work on (most) machines. I'll be doing beta\nreleases for a little while until I can confirm the new version is stable; use BRAT\n(https://github.com/TfTHacker/obsidian42-brat) to easily track Dataview beta versions if you are interested in cutting\nedge features.\n\n---\n\n# 0.4.25\n\nFix #867: Create a container div per taskList to allow for multiple task views.\n\n---\n\n# 0.4.24\n\nRe-release of 0.4.23f since Obsidian does not automatically update between non-semver versions.\n\n---\n\n# 0.4.23f\n\nRemove some code which attempted to make tag queries case-insensitive; I'll reimplement this more generally later (it\nconflicts with existing queries which check tags via `contains(file.tags, \"#Tag\")` and similar).\n\n---\n\n# 0.4.23e\n\nMore task bugfixes / improvements, and a fix that caused task metadata to be duplicated.\n\n---\n\n# 0.4.23d\n\nMore inline field list parsing bug fixes. Hopefully we're back to a nice working order!\n\n---\n\n# 0.4.23c\n\nBugfix which adds support for '1)' style lists, as well as a very annoying null issue due to JavaScript being a very\nsad, very sad language.\n\n---\n\n# 0.4.23b\n\nBugfix for bad inlink/outlink computations; links were not being normalized properly so reverse lookups were not\nworking.\n\n---\n\n# 0.4.23\n\nThe Task Update! This release reworks how dataview handles tasks and list items so that they should be much more\nintuitive to use and interact with:\n\n1. **Subtask Support**: Queries now search over all list items, instead of only over root elements. This should make\n task filtering much more usable, especially if you tend to put tasks under other list items or care specifically\n about subtasks.\n2. **Multiline Support**: Dataview now understands multi-line tasks and renders/updates them correctly.\n3. **Immediately Navigate to Task**: The new task view, aside from looking a little cleaner than previous views, now\n immediately navigates to the task in it's original file on click and selects it.\n4. **Grouping Support**: For DataviewJS users, `dv.taskList` now supports grouping (as produced by `groupBy` and the new\n `groupIn`) natively.\n\nFor DataviewJS users, the task and list representation has changed: `file.tasks` (and the new `file.lists`) contain\nevery single task (including subtasks) in the file, instead of only the root elements. You can return to previous\nbehavior by filtering out tasks with a non-null parent - i.e., `file.tasks.where(task => !task.parent)`. `dv.taskList`\nwill intelligently deal with properly nesting and de-duplicating tasks, so just filter to the tasks you want to render and\nthe API will do the rest.\n\nThis release also includes general backend improvements as we prepare for live-editing in Dataview views, as well as\nseveral community-contributed API improvements:\n\n- `DataArray#groupIn`: For grouping already grouped data, you can now use `array.groupIn(v => ...)`, which will group\n the innermost (original) data in the array instead of the top level groups. This allows for more easily grouping\n recursively, such as `dv.pages().groupBy(page => page.file.folder).groupIn(page => page.title)` producing a grouping\n of folders, then page titles.\n- `substring(string, start[, end])`: The last major missing string function is now available! Take slices of strings.\n- Improved `dv.el()` and other HTML functions - thanks @vitaly.\n- null and undefined entries sort at the end instead of the beginning by default; sorry to those whose code sorts wrong\n because of this, but it is a better default for most people's use cases.\n- All links are now properly normalized to their full paths, fixing many link comparison edge cases in DataviewJS.\n\nDocumentation additions for the new task functionality will be coming out in the next few days. The next release 0.4.24\nis currently targeting expanded `FROM` query support, basic table view improvements, and general exporting functionality\nfor Dataview. See you then!\n\n---\n\n# 0.4.22\n\nThe @pjeby update! This includes several performance improvements suggested by @pjeby to dramatically improve background\nDataview performance as well as reduce some memory pressure. It also includes some minor bug-fixes and preliminary\nfunctionality:\n\n- Target ES2018 for better Promise support\n- Allow parsing shorthands in `dv.date()`.\n- Add additional metadata to inline field rendering which can be styled.\n- Cleanup events & workers on plugin uninstall, improving the Dataview uninstall/disable/reload experience.\n- Add preliminary `CALENDAR` queries - rendering similar to the obsidian-calendar plugin, see the documentation!\n\nDataview should perform much better on startup and when you have lots of tabs open - thanks again to @pjeby.\n\n---\n\n# 0.4.21\n\nBugfix release which primarily fixes issues that Dataview had with the live preview mode in upcoming Obsidian versions;\nDataview live preview should now be functional. Also includes a number of smaller bugfixes.\n\n- Fix #646: Add `date(yesterday)` to create a date 24 hours ago.\n- Fix #618: Luxon is now available on the dataview API (`dv.luxon`).\n- Fix #510: Add `dv.duration()` for parsing durations.\n- Fix #647: All HTML functions in the DataviewJS API now return their rendered objects.\n- Fix #652: Fix parsing of invalid dates.\n- Fix #629: Fix block link parsing.\n- Fix #601: Timezones are now rendered properly and parsed properly in Dataview dates.\n- PR #637: Add `meta(link)` which allows you to access various metadata about a link itself.\n- Various minor null safety fixes.\n- Dataview now reports it's exact version and build time in logs.\n\n---\n\n# 0.4.20\n\nSome feature work (mostly by other contributors) while I while away at section metadata. May also fix a few bugs!\n\n- Fix #448: You can now use the \"Task Completion Tracking\" option to automatically add completion metadata to tasks\n which are checked/unchecked through Dataview. Thanks to @sheeley.\n- Add a search bar to documentation. Thanks to @tzhou.\n- Add new date expressions for the start of the week (`date(sow)`), and the end of the week (`date(eow)`). Thanks\n @Jeamee and @v_mujunma.\n\nSmall minor bugfix / security releases may follow in the near future; otherwise, the next major release will include\nsection and object metadata.\n\n---\n\n# 0.4.19\n\nBugfix release which corrects emoji parsing & localization issues.\n\n- Add `DataArray#into`, which lets you index into objects without flattening.\n- Renamed 'header' to 'section' in task metadata; 'header' will remain around for a few major releases to let people\n naturally migrate.\n- Fix #487: You no longer need spaces around '*' in expressions.\n- Fix #559: Fix unicode issues in variable canonicalization which was causing problems with non-Latin inline field\n keys.\n\n## Duration Parsing\n\nYou can now include multiple units in durations: `dur(8 minutes, 4 seconds)` or `dur(2yr8mo12d)`. You can separate\ndurations by commas, or use the abbreviated syntax with/without spaces.\n\n---\n\n# 0.4.18\n\nBugfix release which fixes bad inline field highlighting if '[' and '(' are mixed on the same line in particular orders.\n\n---\n\n# 0.4.17\n\nMinor feature release to patch up more implementation holes.\n\n## Single File Queries\n\nYou can now query from a specific file (instead of just folders and tags) by specifying the full file path:\n\n```\nTASK FROM \"dataview/Test\"\n...\n```\n\nThis is primarily useful for task queries, but will soon be useful for section and object queries in the near future as\nwell.\n\n## Better Inline Field Highlighting\n\nThe CSS for inline field highlighting has been fixed and some compatibility issues improved, so it should work on all\nthemes now instead of only a few.\n\n## dv.el()\n\nDataviewJS now has `dv.el()`, which is like existing functions like `dv.paragraph` and `dv.span` but can create any\nHTML element type; for example:\n\n```js\ndv.el(\"b\", \"Text!\");\ndv.el(\"i\", 18);\n```\n\n---\n\n# 0.4.16\n\nSmall performance release which substantially reduces the impact Dataview has on vault loading times (by spreading out\nfile loading). The Dataview Index is now also eagerly initialized, so plugin consumers of the API can immediately start\nusing it instead of waiting for the `dataview:api-ready` event.\n\n---\n\n# 0.4.15\n\nA simple fix for #537 which properly 'awaits' value rendering in `dv.view()`. Fixes issues with values rendering out of\norder.\n\n---\n\n# 0.4.14\n\nSmall bugfix release.\n\n- Fixes inline field evaluation when using the new fancy highlighting.\n- You can now configure whether task links should show up at the beginning or end of the task (or just disable them)\n in the \"Task Link Location\" setting.\n- Most setting updates will immediately be applied to existing Dataviews.\n\n---\n\n# 0.4.13\n\nBugfix release which adds fancy rendering to inline-inline fields and includes a few bugfixes.\n\n## Pretty Inline Fields\n\nInline fields of the form `[key:: value]` will now be rendered with fancy new HTML! By default, they are rendered with\nboth the key and value. You can only render the value using parenthesis instead: `(key:: value)`. You can disable\nthis feature in the configuration.\n\nFull-line inline fields (that Dataview has supported for a long time) will gain similar rendering support soon; in the\nmeanwhile, give the new syntax a try!\n\n### Task Linking\n\nTasks now render with a link to the page/section that they are defined in, making `GROUP BY` and custom task\nediting easier to do:\n\n- [ ] A Task. 🔗\n- [ ] Another Task. 🔗\n - [ ] Some Random Subtask. 🔗\n\nYou can configure the symbol for the link or disable it altogether.\n\n### Improving DataviewJS Posture\n\nI am currently actively looking into improving DataviewJS sandboxing and general security posture. As a first small step\nin this, I have made DataviewJS opt-in instead of opt-out, and added a separate control for Inline DataviewJS. You may\nneed to re-enable it in your settings if you use it.\n\nMore improvements and better JavaScript sandboxing will follow.\n\n---\n\n# 0.4.12-hotfix1\n\nRe-release of 0.4.12 that fixes an important indexing issue.\n\n- Fix #505: Use `completion` instead of `completed` when setting task completion time.\n- Fix #509: Add `startswith` / `endswith` string functions.\n- Fix #488: Add `padleft` and `padright`, and `string`.\n- Fix #506, #512: Fix date comparisons due to a bizarre date zone issue.\n\n---\n\n# 0.4.12\n\nBugfix release following up 0.4.11 which includes a few minor function additions.\n\n- Fix #512: Strange zone issue causing dates to not be equal.\n- Fix #506: Same as #512.\n- Fix #488: Add `padleft` / `padright` functions.\n- Fix #509: Add `startswith` and `endswith` functions.\n- Fix #505: Correctly read completion dates for tasks from `completion`.\n\nThis release also includes improved testing thanks to mocking Obsidian plugin APIs!\n\n---\n\n# 0.4.11\n\nFixes task behavior and adds \"truly inline\" fields!\n\n## Improved Task Behavior\n\nTask queries are now much improved from their primitive foundations - you can now filter, sort, and group them! The FROM\nblock is still page-based, sadly, though you can simply use `WHERE` instead if desired. For example, you can now access\ntask fields like `text`, `line`, or `completed`:\n\n```\nTASK WHERE contains(text, \"#tag\")\nWHERE !completed\nGROUP BY file.folder\n```\n\nThe full list of all available task metadata can be found\n[here](https://blacksmithgu.github.io/obsidian-dataview/data-annotation/#tasks); tasks include all the information\nneeded to uniquely identify them, and automatically inherit all of the metadata from their parent file as well (so you\ncan access `file.name`, for example). You can also annotate tasks with inline fields, as described in the section below.\n\nThere is some additional UX work to be done - primarily on more easily allowing you to navigate to where the task is\ndefined, as well as render tasks in views other than the `TASK` view. The semantics of how grouping works (to make it\nmore intuitive/useful than it currently is) will likely also be revisited.\n\n## Inline Inline Fields\n\nEarly support for truly inline fields have been added, where you can add metadata in the middle of a sentence. It looks\nsimilar to existing inline field syntax, but with brackets or parenthesis:\n\n```\nI would rate this a [rating:: 6]. It was (thoughts:: acceptable).\n```\n\nImproved rendering for all inline fields is coming in an upcoming update to improve the visual look of these inline\nfields.\n\n\n## Issues\n\n- Fix #496: Fix task `SORT` functionality to do something.\n- Fix #492: Tasks now properly annotated with parent file information.\n- Fix #498: Fix task checking/unchecking logic (which broke due to a change in the task regex...).\n\n---\n\n# Initial\n\nStart of the automatic changelog.\n"
},
{
"path": "docs/docs/friends.md",
"content": "# Friends of Dataview\n\nA list of plugins which may be helpful for Dataview related workflows:\n\n - [MetaEdit](https://github.com/chhoumann/MetaEdit) - Add or update yaml properties and Dataview fields easily\n\nAnother non-exhaustive list of plugins which use Dataview for some of the heavy-lifting required for their features:\n\n - [Kanban](https://github.com/mgmeyers/obsidian-kanban) - Create markdown-backed Kanban boards in Obsidian\n - [Breadcrumbs](http://publish.obsidian.md/breadcrumbs-docs) - Gives you a way to visualize a custom-built hierarchy in your Obsidian vault\n - [Supercharged Links](https://github.com/mdelobelle/obsidian_supercharged_links) - Allows you to style links in your Obsidian vault based on note metadata\n\nA full list can be found using GitHub's [Dependents](https://github.com/blacksmithgu/obsidian-dataview/network/dependents) feature.\n"
},
{
"path": "docs/docs/index.md",
"content": "# Overview\n\nDataview is a live index and query engine over your personal knowledge base. You can [**add metadata**](annotation/add-metadata.md) to your notes and **query** them with the [**Dataview Query Language**](queries/structure.md) to list, filter, sort or group your data. Dataview keeps your queries always up to date and makes data aggregation a breeze.\n\nYou could\n\n- Track your sleep by recording it in daily notes, and automatically create weekly tables of your sleep schedule.\n- Automatically collect links to books in your notes, and render them all sorted by rating.\n- Automatically collect pages associated with today's date and show them in your daily note.\n- Find pages with no tags for follow-up, or show pretty views of specifically-tagged pages.\n- Create dynamic views which show upcoming birthdays or events recorded in your notes\n\nand many more things.\n\n!!! hint \"Dataview gives you a fast way to search, display and operate on indexed data in your vault!\"\n\nDataview is highly generic and high performance, scaling up to hundreds of thousands of annotated notes without issue. \n\nIf the built in [query language](queries/structure.md) is insufficient for your purpose, you can run arbitrary\nJavaScript against the [dataview API](api/intro.md) and build whatever utility you might need yourself, right in your notes.\n\n!!! info \"Dataview is about displaying, not editing\"\n Dataview is meant for displaying and calculating data. It is not meant to edit your notes/metadata and will always leave them untouched (... except if you're checking a [Task](queries/query-types.md#task) through Dataview.)\n\n## How to Use Dataview\n\nDataview consists of two big building blocks: **Data Indexing** and **Data Querying**. \n\n!!! info \"More details on the linked documentation pages\"\n The following sections should give you a general overview about what you can do with dataview and how. Be sure to visit the linked pages to find out more about the individual parts.\n\n### Data Indexing\n\nDataview operates on metadata in your Markdown files. It cannot read everything in your vault, but only specific data. Some of your content, like tags and bullet points (including tasks), are [available automatically](annotation/add-metadata.md#implicit-fields) in Dataview. You can add other data through **fields**, either on top of your file [per YAML Frontmatter](annotation/add-metadata.md#frontmatter) or in the middle of your content with [Inline Fields](annotation/add-metadata.md#inline-fields) via the `[key:: value]` syntax. Dataview _indexes_ these data to make it available for you to query. \n\n!!! hint \"Dataview indexes [certain information](annotation/add-metadata.md#implicit-fields) like tags and list items and the data you add via fields. Only indexed data is available in a Dataview query!\"\n\nFor example, a file might look like this:\n\n```markdown\n---\nauthor: \"Edgar Allan Poe\"\npublished: 1845\ntags: poems\n---\n\n# The Raven\n\nOnce upon a midnight dreary, while I pondered, weak and weary,\nOver many a quaint and curious volume of forgotten lore—\n```\n\nOr like this:\n\n```markdown\n#poems\n\n# The Raven\n\nFrom [author:: Edgar Allan Poe], written in (published:: 1845)\n\nOnce upon a midnight dreary, while I pondered, weak and weary,\nOver many a quaint and curious volume of forgotten lore—\n```\n\nIn terms of indexed metadata (or what you can query), they are identical, and only differ in their annotation style. How you want to [annotate your metadata](annotation/add-metadata.md) is up to you and your personal preference. With this file, you'd have the **metadata field** `author` available and everything Dataview provides you [automatically as implicit fields](annotation/metadata-pages.md), like the tag or note title. \n\n!!! attention \"Data needs to be indexed\"\n In the above example, you _do not_ have the poem itself available in Dataview: It is a paragraph, not a metadata field and not something Dataview indexes automatically. It is not part of Dataviews index, so you won't be able to query it.\n\n### Data Querying\n\nYou can access **indexed data** with the help of **Queries**.\n\nThere are **three different ways** you can write a Query: With help of the [Dataview Query Language](queries/dql-js-inline.md#dataview-query-language-dql), as an [inline statement](queries/dql-js-inline.md#inline-dql) or in the most flexible but most complex way: as a [Javascript Query](queries/dql-js-inline.md#dataview-js). \n\nThe **Dataview Query Language** (**DQL**) gives you a broad and powerful toolbelt to query, display and operate on your data. An [**inline query**](queries/dql-js-inline.md#inline-dql) gives you the possibility to display exactly one indexed value anywhere in your note. You can also do calculations this way. With **DQL** at your hands, you'll be probably fine without any Javascript through your data journey.\n\nA DQL Query consists of several parts:\n\n- Exactly one [**Query Type**](queries/query-types.md) that determines what your Query Output looks like\n- None or one [**FROM statement**](queries/data-commands.md#from) to pick a specific tag or folder (or another [source](reference/sources.md)) to look at\n- None to multiple [**other Data Commands**](queries/data-commands.md) that help you filter, group and sort your wanted output\n\nFor example, a Query can look like this:\n\n~~~markdown\n```dataview\nLIST\n```\n~~~\n\nwhich list all files in your vault. \n\n!!! info \"Everything but the Query Type is optional\"\n The only thing you need for a valid DQL Query is the Query Type (and on [CALENDAR](queries/query-types.md#calendar)s, a date field.)\n\n A more restricted Query might look like this:\n\n~~~markdown\n```dataview\nLIST\nFROM #poems\nWHERE author = \"Edgar Allan Poe\"\n```\n~~~\n\nwhich lists all files in your vault that have the tag `#poems` and a [field](annotation/add-metadata.md) named `author` with the value `Edgar Allan Poe`. This query would find our example page from above. \n\n`LIST` is only one out of four [Query Types](queries/query-types.md) you can use. For example, with a `TABLE`, we could add some more information to our output: \n\n\n~~~markdown\n```dataview\nTABLE author, published, file.inlinks AS \"Mentions\"\nFROM #poems\n```\n~~~\n\nThis'll give you back a result like:\n\n| File (3) |\tauthor |\tpublished\t| Mentions |\n| -------- | ------- | ---------- | -------- |\n| The Bells |\tEdgar Allan Poe |\t1849 | |\t\n| The New Colossus |\tEmma Lazarus | 1883\t| - [[Favorite Poems]] |\t\n| The Raven |\tEdgar Allan Poe |\t1845 | - [[Favorite Poems]] |\t\n\nThat's not where the capabilities of dataview end, though. You can also **operate on your data** with help of [**functions**](reference/functions.md). Mind that these operations are only made inside your query - your **data in your files stays untouched**.\n\n~~~markdown\n```dataview\nTABLE author, date(now).year - published AS \"Age in Yrs\", length(file.inlinks) AS \"Counts of Mentions\"\nFROM #poems\n```\n~~~\n\ngives you back\n\n| File (3) |\tauthor |\tAge in Yrs\t| Count of Mentions |\n| -------- | ------- | ---------- | -------- |\n| The Bells\t| Edgar Allan Poe |\t173 | 0 |\n| The New Colossus\t| Emma Lazarus |\t139 |\t1 |\n| The Raven |\tEdgar Allan Poe |\t177 | 1 |\t\n\n!!! info \"Find more examples [here](resources/examples.md).\"\n\nAs you can see, dataview doesn't only allow you to aggregate your data swiftly and always up to date, it also can help you with operations to give you new insights on your dataset. Browse through the documentation to find out more on how to interact with your data.\n\n Have fun exploring your vault in new ways! \n\n## Resources and Help\n\nThis documentation is not the only place that can help you out on your data journey. Take a look at [Resources and Support](./resources/resources-and-support.md) for a list of helpful pages and videos.\n"
},
{
"path": "docs/docs/queries/data-commands.md",
"content": "# Data Commands\n\nThe different commands that dataview queries can be made up of. Commands are\nexecuted in order, and you can have duplicate commands (so multiple `WHERE`\nblocks or multiple `GROUP BY` blocks, for example).\n\n## FROM\n\nThe `FROM` statement determines what pages will initially be collected and passed onto the other commands for further\nfiltering. You can select from any [source](../reference/sources.md), which currently means by folder, by tag, or by incoming/outgoing links.\n\n- **Tags**: To select from a tag (and all its subtags), use `FROM #tag`.\n- **Folders**: To select from a folder (and all its subfolders), use `FROM \"folder\"`.\n- **Single Files**: To select from a single file, use `FROM \"path/to/file\"`.\n- **Links**: You can either select links TO a file, or all links FROM a file.\n - To obtain all pages which link TO `[[note]]`, use `FROM [[note]]`.\n - To obtain all pages which link FROM `[[note]]` (i.e., all the links in that file), use `FROM outgoing([[note]])`.\n\nYou can compose these filters in order to get more advanced sources using `and` and `or`.\n\n- For example, `#tag and \"folder\"` will return all pages in `folder` and with `#tag`.\n- `[[Food]] or [[Exercise]]` will give any pages which link to `[[Food]]` OR `[[Exercise]]`.\n\nYou can also \"negate\" sources to obtain anything that does NOT match a source using `-`:\n\n- `-#tag` will exclude files which have the given tag.\n- `#tag and -\"folder\"` will only include files tagged `#tag` which are NOT in `\"folder\"`.\n\n## WHERE\n\nFilter pages on fields. Only pages where the clause evaluates to `true` will be yielded.\n\n```\nWHERE \n```\n\n1. Obtain all files which were modified in the last 24 hours:\n\n ```sql\n LIST WHERE file.mtime >= date(today) - dur(1 day)\n ```\n\n2. Find all projects which are not marked complete and are more than a month old:\n\n ```sql\n LIST FROM #projects\n WHERE !completed AND file.ctime <= date(today) - dur(1 month)\n ```\n\n## SORT\n\nSorts all results by one or more fields.\n\n```\nSORT date [ASCENDING/DESCENDING/ASC/DESC]\n```\n\nYou can also give multiple fields to sort by. Sorting will be done based on the first field. Then, if a tie occurs, the second field will be used to sort the tied fields. If there is still a tie, the third sort will resolve it, and so on.\n\n```\nSORT field1 [ASCENDING/DESCENDING/ASC/DESC], ..., fieldN [ASC/DESC]\n```\n\n## GROUP BY\n\nGroup all results on a field. Yields one row per unique field value, which has 2 properties: one corresponding to the field being grouped on, and a `rows` array field which contains all of the pages that matched.\n\n```\nGROUP BY field\nGROUP BY (computed_field) AS name\n```\n\nIn order to make working with the `rows` array easier, Dataview supports field \"swizzling\". If you want the field `test` from every object in the `rows` array, then `rows.test` will automatically fetch the `test` field from every object in `rows`, yielding a new array.\nYou can then apply aggregation operators like `sum()` or `flat()` over the resulting array.\n\n## FLATTEN\n\nFlatten an array in every row, yielding one result row per entry in the array.\n\n```\nFLATTEN field\nFLATTEN (computed_field) AS name\n```\n\nFor example, flatten the `authors` field in each literature note to give one row per author:\n\n=== \"Query\"\n ```sql\n TABLE authors FROM #LiteratureNote\n FLATTEN authors\n ```\n=== \"Output\"\n |File|authors|\n |-|-|\n |stegEnvironmentalPsychologyIntroduction2018 SN|Steg, L.|\n |stegEnvironmentalPsychologyIntroduction2018 SN|Van den Berg, A. E.|\n |stegEnvironmentalPsychologyIntroduction2018 SN|De Groot, J. I. M.|\n |Soap Dragons SN|Robert Lamb|\n |Soap Dragons SN|Joe McCormick|\n |smithPainAssaultSelf2007 SN|Jonathan A. Smith|\n |smithPainAssaultSelf2007 SN|Mike Osborn|\n\nA good use of this would be when there is a deeply nested list that you want to use more easily.\nFor example, `file.lists` or `file.tasks`.\nNote the simpler query though the end results are slightly different (grouped vs non-grouped).\nYou can use a `GROUP BY file.link` to achieve identical results but would need to use `rows.T.text` as described earlier.\n\n```\ntable T.text as \"Task Text\"\nfrom \"Scratchpad\"\nflatten file.tasks as T\nwhere T.text\n```\n\n```\ntable filter(file.tasks.text, (t) => t) as \"Task Text\"\nfrom \"Scratchpad\"\nwhere file.tasks.text\n```\n\n`FLATTEN` makes it easier to operate on nested lists since you can then use simpler where conditions on them as opposed to using functions like `map()` or `filter()`.\n\n## LIMIT\n\nRestrict the results to at most N values.\n\n```\nLIMIT 5\n```\n\nCommands are processed in the order they are written, so the following sorts the results *after* they have already been limited:\n\n```\nLIMIT 5\nSORT date ASCENDING\n```\n"
},
{
"path": "docs/docs/queries/differences-to-sql.md",
"content": "\n# Dataview Query Language (DQL) and SQL\n\nIf you are familiar with SQL and experienced in writing SQL queries, you might approach writing a DQL query in a similar way. However, DQL is significantly different from SQL.\n\nA DQL query is **executed from top to bottom**, line-by-line. It is more like a computer program than a typical SQL query.\n\nWhen a line is evaluated, it produces a result set and **passes the whole set on to the next DQL line** which will manipulate the set that it received from the previous line. This is why in DQL it is possible, for example, to have multiple WHERE clauses. But in DQL it is not a 'clause' but a 'data command'. Every line of a DQL query (except the 1st and 2nd lines) is a 'data command'.\n\n## Anatomy of a DQL query\n\nInstead of starting with SELECT, a DQL query starts with a word determining the Query Type, which determines how your final result will be rendered on screen (a table, a list, a task list, or a calendar). Then follows the list of fields, which is actually very similar to the column list you put after a SELECT statement.\n\nThe next line starts with FROM which is not followed by a table name but by a complex expression, similar to an SQL WHERE clause. Here you can filter on many things, like tags in files, file names, path names, etc. In the background, this command already produces a result set which will be our initial set for further data manipulation by 'data commands' on subsequent lines.\n\nYou can have as many following lines as you want. Each will start with a [data command](data-commands.md) and will re-shape the result set it received from the previous line. For example:\n\n- The WHERE data command will only keep those lines from the result set which match a given condition. This means that, unless all data in the result set matches the condition, this command will pass on a smaller result set to the next line than it received from the previous line. Unlike in SQL, you can have as many WHERE commands as you like.\n- The FLATTEN data command is not found in common SQL but in DQL you can use it to reduce the depth of the result set.\n- DQL, similarly to SQL, has a GROUP BY command but this can also be used multiple times, which is not possible in common SQL. You can even do several SORT or GROUP BY commands one after the other.\n"
},
{
"path": "docs/docs/queries/dql-js-inline.md",
"content": "# DQL, JS and Inlines\n\nOnce you've added [useful data to relevant pages](../annotation/add-metadata.md), you'll want to actually display it somewhere or operate on it. Dataview\nallows this in four different ways, all of which are written in codeblocks directly in your Markdown and live-reloaded\nwhen your vault changes.\n\n## Dataview Query Language (DQL)\n\nThe [**Dataview Query Language**](structure.md) (for short **DQL**) is a SQL-like language and Dataviews core functionality. It supports [four Query Types](./query-types.md) to produce different outputs, [data commands](./data-commands.md) to refine, resort or group your result and [plentiful functions](../reference/functions.md) which allow numerous operations and adjustments to achieve your wanted output.\n\n!!! warning Differences to SQL\n If you are familiar with SQL, please read [Differences to SQL](differences-to-sql.md) to avoid confusing DQL with SQL.\n\nYou create a **DQL** query with a codeblock that uses `dataview` as type:\n\n~~~\n```dataview\nTABLE rating AS \"Rating\", summary AS \"Summary\" FROM #games\nSORT rating DESC\n```\n~~~\n\n!!! attention \"Use backticks\"\n A valid codeblock needs to use backticks (\\`) on start and end (three each). Do not confuse the backtick with the similar looking apostrophe ' !\n\nFind a explanation how to write a DQL Query under the [query language\nreference](structure.md). If you learn better by example, take a look at the [query examples](../resources/examples.md).\n\n## Inline DQL\n\nA Inline DQL uses a inline block format instead of a code block and a configurable prefix to mark this inline code block as a DQL block.\n\n~~~\n`= this.file.name`\n~~~\n\n!!! info \"Change of DQL prefix\"\n You can change the `=` to another token (like `dv:` or `~`) in Dataviews' settings under \"Codeblock Settings\" > \"Inline Query Prefix\"\n\nInline DQL Queries display **exactly one value** somewhere in the middle of your note. They seamlessly blend into the content of your note:\n\n~~~markdown\nToday is `= date(today)` - `= [[exams]].deadline - date(today)` until exams!\n~~~\n\nwould, for example, render to\n\n~~~markdown\nToday is November 07, 2022 - 2 months, 5 days until exams!\n~~~\n\n**Inline DQL** queries always display exactly one value, not a list (or table) of values. You can access the properties of the **current page** via prefix `this.` or a different page via `[[linkToPage]].`.\n\n~~~markdown\n`= this.file.name`\n`= this.file.mtime`\n`= this.someMetadataField`\n`= [[secondPage]].file.name`\n`= [[secondPage]].file.mtime`\n`= [[secondPage]].someMetadataField`\n~~~\n\nYou can use everything available as [expressions](../reference/expressions.md) and [literals](../reference/literals.md) in an Inline DQL Query, including [functions](../reference/functions.md). Query Types and Data Commands, on the other hand, are **not available in Inlines.**\n\n~~~markdown\nAssignment due in `= this.due - date(today)`\nFinal paper due in `= [[Computer Science Theory]].due - date(today)`\n\n🏃♂️ Goal reached? `= choice(this.steps > 10000, \"YES!\", \"**No**, get moving!\")`\n\nYou have `= length(filter(link(dateformat(date(today), \"yyyy-MM-dd\")).file.tasks, (t) => !t.completed))` tasks to do. `= choice(date(today).weekday > 5, \"Take it easy!\", \"Time to get work done!\")`\n~~~\n\n## Dataview JS\n\nThe dataview [JavaScript API](../api/intro.md) gives you the full power of JavaScript and provides a DSL for pulling\nDataview data and executing queries, allowing you to create arbitrarily complex queries and views. Similar to the query\nlanguage, you create Dataview JS blocks via a `dataviewjs`-annotated codeblock:\n\n~~~java\n```dataviewjs\nlet pages = dv.pages(\"#books and -#books/finished\").where(b => b.rating >= 7);\nfor (let group of pages.groupBy(b => b.genre)) {\n dv.header(3, group.key);\n dv.list(group.rows.file.name);\n}\n```\n~~~\n\nInside of a JS dataview block, you have access to the full dataview API via the `dv` variable. For an explanation of\nwhat you can do with it, see the [API documentation](../api/code-reference.md), or the [API\nexamples](../api/code-examples.md).\n\n!!! attention \"Advanced usage\"\n Writing Javascript queries is a advanced technique that requires understanding in programming and JS. Please be aware that JS Queries have access to your file system and be cautious when using other peoples' JS Queries, especially when they are not publicly shared through the Obsidian Community.\n\n## Inline Dataview JS\n\nSimilar to the query language, you can write JS inline queries, which let you embed a computed JS value directly. You\ncreate JS inline queries via inline code blocks:\n\n```\n`$= dv.current().file.mtime`\n```\n\nIn inline DataviewJS, you have access to the `dv` variable, as in `dataviewjs` codeblocks, and can make all of the same calls. The result\nshould be something which evaluates to a JavaScript value, which Dataview will automatically render appropriately.\n\nUnlike Inline DQL queries, Inline JS queries do have access to everything a Dataview JS Query has available and can hence query and output multiple pages.\n\n!!! info \"Change of Inline JS prefix\"\n You can change the `$=` to another token (like `dvjs:` or `$~`) in Dataviews' settings under \"Codeblock Settings\" > \"Javascript Inline Query Prefix\"\n"
},
{
"path": "docs/docs/queries/query-types.md",
"content": "# Query Types\n\nThe **Query Type** determines how the output of your dataview query looks like. It is the **first and only mandatory** specification you give to a dataview query. There are four available: `LIST`, `TABLE`, `TASK` and `CALENDAR`.\n\nThe Query Type also determines which **information level** a query is executed on. `LIST`, `TABLE` and `CALENDAR` operate at **page level** whereas `TASK` queries operate at the `file.tasks` level. More on that in the `TASK` Query Type.\n\nYou can combine **every Query Type with all available [Data Commands](data-commands.md)** to refine your result set. Read more about the interconnection between Query Types and Data Commands on [How to Use Dataview](../index.md#how-to-use-dataview) and the [structure page](structure.md).\n\n!!! summary \"Query Type\"\n The Query Type determines the output format of a query. It's the only mandatory information for a query.\n\n## LIST\n\n`LIST` queries output a bullet point list consisting of your file links or the group name, if you decided to [group](data-commands.md#group-by). You can specify up to **one additional information** to output alongside your file or group information.\n\n!!! summary \"Query Type `LIST`\"\n `LIST` outputs a bullet point list of page links or Group keys. You can specify one additional information to show for each result.\n\nThe simplest LIST query outputs a bullet point list of all files in your vault:\n\n~~~\n```dataview\nLIST\n```\n~~~\n\n**Output**\n\n\n- [Classic Cheesecake](#)\n- [Git Basics](#)\n- [How to fix Git Cheatsheet](#)\n- [League of Legends](#)\n- [Pillars of Eternity 2](#)\n- [Stardew Valley](#)\n- [Dashboard](#)\n\n\nbut you can, of course, use [data commands](data-commands.md) to restrict which pages you want to have listed:\n\n~~~\n```dataview\nLIST\nFROM #games/mobas OR #games/crpg\n```\n~~~\n\n**Output**\n\n- [League of Legends](#)\n- [Pillars of Eternity 2](#)\n\n### Output an additional information\n\nTo add a **additional information** to your query, specify it right after the `LIST` command and before possibly available data commands:\n\n~~~\n```dataview\nLIST file.folder\n```\n~~~\n\n**Output**\n\n\n- [Classic Cheesecake](#): Baking/Recipes\n- [Git Basics](#): Coding\n- [How to fix Git Cheatsheet](#): Coding/Cheatsheets\n- [League of Legends](#): Games\n- [Pillars of Eternity 2](#): Games\n- [Stardew Valley](#): Games/finished\n- [Dashboard](#):\n\nYou can only add **one** additional information, not multiple. But you can **specify a computed value** instead of a plain meta data field, which can contain information of multiple fields:\n\n~~~\n```dataview\nLIST \"File Path: \" + file.folder + \" _(created: \" + file.cday + \")_\"\nFROM \"Games\"\n```\n~~~\n\n**Output**\n\n- [League of Legends](#): File Path: Games _(created: May 13, 2021)_\n- [Pillars of Eternity 2](#): File Path: Games _(created: February 02, 2022)_\n- [Stardew Valley](#): File Path: Games/finished _(created: April 04, 2021)_\n\n### Grouping\n\nA **grouped list** shows their group keys, and only the group keys, by default:\n\n~~~\n```dataview\nLIST\nGROUP BY type\n```\n~~~\n\n**Output**\n\n- game\n- knowledge\n- moc\n- recipe\n- summary\n\nA common use-case on grouped `LIST` queries is to add the file links to the output by specifying them as the additional information:\n\n~~~\n```dataview\nLIST rows.file.link\nGROUP BY type\n```\n~~~\n\n- game:\n - [Stardew Valley](#)\n - [League of Legends](#)\n - [Pillars of Eternity 2](#)\n- knowledge:\n - [Git Basics](#)\n- moc:\n - [Dashboard](#)\n- recipe:\n - [Classic Cheesecake](#)\n- summary:\n - [How to fix Git Cheatsheet](#)\n\n### LIST WITHOUT ID\n\nIf you don't want the file name or group key included in the list view, you can use `LIST WITHOUT ID`. `LIST WITHOUT ID` works the same as `LIST`, but it does not output the file link or group name if you add an additional information.\n\n~~~\n```dataview\nLIST WITHOUT ID\n```\n~~~\n\n**Output**\n\n\n- [Classic Cheesecake](#)\n- [Git Basics](#)\n- [How to fix Git Cheatsheet](#)\n- [League of Legends](#)\n- [Pillars of Eternity 2](#)\n- [Stardew Valley](#)\n- [Dashboard](#)\n\nIt's the same as `LIST`, because it does not contain an additional information!\n\n~~~\n```dataview\nLIST WITHOUT ID type\n```\n~~~\n\n**Output**\n\n- moc\n- recipe\n- summary\n- knowledge\n- game\n- game\n- game\n\n`LIST WITHOUT ID` can be handy if you want to output computed values, for example.\n\n~~~\n```dataview\nLIST WITHOUT ID length(rows) + \" pages of type \" + key\nGROUP BY type\n```\n~~~\n\n**Output**\n\n- 3 pages of type game\n- 1 pages of type knowledge\n- 1 pages of type moc\n- 1 pages of type recipe\n- 1 pages of type summary\n\n## TABLE\n\nThe `TABLE` query types outputs page data as a tabular view. You can add zero to multiple meta data fields to your `TABLE` query by adding them as a **comma separated list**. You can not only use plain meta data fields as columns, but specify **calculations** as well. Optionally, you can specify a **table header** via the `AS ` syntax. Like all other query types, you can refine your result set for your query with [data commands](data-commands.md).\n\n!!! summary \"`TABLE` Query Type\"\n `TABLE` queries render a tabular view of any number of meta data values or calculations. It is possible to specify column headers via `AS `.\n\n~~~\n```dataview\nTABLE\n```\n~~~\n\n**Output**\n\n| File (7) |\n| ----- |\n| [Classic Cheesecake](#) |\n| [Git Basics](#) |\n| [How to fix Git Cheatsheet](#) |\n| [League of Legends](#) |\n| [Pillars of Eternity 2](#) |\n| [Stardew Valley](#) |\n| [Dashboard](#) |\n\n!!! hint \"Changing the first column header name\"\n You can change the name of the first column header (by default \"File\" or \"Group\") via the Dataview Settings under Table Settings -> Primary Column Name / Group Column Name.\n If you want to change the name only for one specific `TABLE` query, have a look at `TABLE WITHOUT ID`.\n\n!!! info \"Disabling Result count\"\n The first column always shows the result count. If you do not want to get it displayed, you can disable it in Dataview's settings (\"Display result count\", available since 0.5.52).\n\nOf course, a `TABLE` is made for specifying one to multiple additional information:\n\n~~~\n```dataview\nTABLE started, file.folder, file.etags\nFROM #games\n```\n~~~\n\n**Output**\n\n| File (3) | started | file.folder | file.etags |\n| --- | --- | --- | --- |\n| [League of Legends](#) | \tMay 16, 2021 | \tGames\t | - #games/moba |\n| [Pillars of Eternity 2](#) | \tApril 21, 2022 | \tGames\t | - #games/crpg |\n| [Stardew Valley](#) | \tApril 04, 2021 | \tGames/finished\t | - #games/simulation |\n\n!!! hint \"Implicit fields\"\n Curious about `file.folder` and `file.etags`? Learn more about [implicit fields on pages](../annotation/metadata-pages.md).\n\n### Custom Column Headers\n\nYou can specify **custom headings** for your columns by using the `AS` syntax:\n\n~~~\n```dataview\nTABLE started, file.folder AS Path, file.etags AS \"File Tags\"\nFROM #games\n```\n~~~\n\n**Output**\n\n| File (3) | started | Path | File Tags |\n| --- | --- | --- | --- |\n| [League of Legends](#) | \tMay 16, 2021 | \tGames\t | - #games/moba |\n| [Pillars of Eternity 2](#) | \tApril 21, 2022 | \tGames\t | - #games/crpg |\n| [Stardew Valley](#) | \tApril 04, 2021 | \tGames/finished\t | - #games/simulation |\n\n!!! info \"Custom headers with spaces\"\n If you want to use a custom header with spaces, like `File Tags`, you need to wrap it into double quotes: `\"File Tags\"`.\n\nThis is especially useful when you want to use **calculations or expressions as column values**:\n\n~~~\n```dataview\nTABLE\ndefault(finished, date(today)) - started AS \"Played for\",\nfile.folder AS Path,\nfile.etags AS \"File Tags\"\nFROM #games\n```\n~~~\n\n**Output**\n\n| File (3) | Played for | Path | File Tags |\n| --- | --- | --- | --- |\n| [League of Legends](#) | \t1 years, 6 months, 1 weeks | \tGames\t | - #games/moba |\n| [Pillars of Eternity 2](#) | \t7 months, 2 days | \tGames\t | - #games/crpg |\n| [Stardew Valley](#) | \t4 months, 3 weeks, 3 days | \tGames/finished\t | - #games/simulation |\n\n!!! hint \"Calculations and expressions\"\n Learn more about the capability of computing expressions and calculations under [expressions](../reference/expressions.md) and [functions](../reference/functions.md).\n\n### TABLE WITHOUT ID\n\nIf you don't want the first column (\"File\" or \"Group\" by default), you can use `TABLE WITHOUT ID`. `TABLE WITHOUT ID` works the same as `TABLE`, but it does not output the file link or group name as a first column if you add additional information.\n\nYou can use this if you, for example, output another identifying value:\n\n~~~\n```dataview\nTABLE WITHOUT ID\nsteamid,\nfile.etags AS \"File Tags\"\nFROM #games\n```\n~~~\n\n**Output**\n\n| steamid (3) | File Tags |\n| --- | --- |\n| 560130 | - #games/crog |\n| - | - #games/moba |\n| 413150 | - #games/simulation |\n\nAlso, you can use `TABLE WITHOUT ID` if you want to **rename the first column for one specific query**.\n\n~~~\n```dataview\nTABLE WITHOUT ID\nfile.link AS \"Game\",\nfile.etags AS \"File Tags\"\nFROM #games\n```\n~~~\n\n**Output**\n\n| Game (3) | File Tags |\n| --- | --- |\n| [League of Legends](#) | - #games/moba |\n| [Pillars of Eternity 2](#) | - #games/crpg |\n| [Stardew Valley](#) | - #games/simulation |\n\n!!! info \"Renaming the first column in general\"\n If you want to rename the first column in all cases, change the name in Dataviews settings under Table Settings.\n\n## TASK\n\nThe `TASK` Query outputs **an interactive list of all tasks in your vault** that match the given [data commands](data-commands.md) (if any). `TASK` queries are special compared to the other Query Types because they do give back **Tasks as results and not pages**. This implies that all [data commands](data-commands.md) operate on **Task level** and makes it possible to granularly filter your tasks i.e. for their status or meta data specified on the task itself.\n\nAlso, `TASK` Queries are the only possibility to **manipulate your files through DQL**. Normally, Dataview does not touch the content of your files; however, if you check a task through a dataview query, it'll get **checked in its original file, too**. In the Dataview Settings under \"Task Settings\", you can opt-in to automatically set a `completion` meta data field when checking a task in dataview. Mind though that this only works if you check the task inside a dataview block.\n\n!!! summary \"`TASK` Query Type\"\n `TASK` queries render an interactive list of all tasks in your vault. `TASK` Queries are executed on **task level**, not page level, allowing for task-specific filtering. This is the only command in dataview that modifies your original files if interacted with.\n\n~~~\n```dataview\nTASK\n```\n~~~\n\n**Output**\n\n- [ ] Buy new shoes #shopping\n- [ ] Mail Paul about training schedule\n- [ ] Finish the math assignment\n - [x] Finish Paper 1 [due:: 2022-08-13]\n - [ ] Read again through chapter 3 [due:: 2022-09-01]\n - [x] Write a cheatsheet [due:: 2022-08-02]\n - [ ] Write a summary of chapter 1-4 [due:: 2022-09-12]\n- [x] Hand in physics\n- [ ] Get new pillows for mom #shopping\n- [x] Buy some working pencils #shopping\n\nYou can use [data commands](data-commands.md) like for all other Query Types. Data Commands are executed on task level, making [implicit fields on tasks](../annotation/metadata-tasks.md) directly available.\n\n~~~\n```dataview\nTASK\nWHERE !completed AND contains(tags, \"#shopping\")\n```\n~~~\n\n**Output**\n\n- [ ] Buy new shoes #shopping\n- [ ] Get new pillows for mom #shopping\n\nA common use case for tasks is to **group tasks by their originating file**:\n\n~~~\n```dataview\nTASK\nWHERE !completed\nGROUP BY file.link\n```\n~~~\n\n**Output**\n\n[2022-07-30](#) (1)\n\n- [ ] Finish the math assignment\n - [ ] Read again through chapter 3 [due:: 2022-09-01]\n - [ ] Write a summary of chapter 1-4 [due:: 2022-09-12]\n\n[2022-09-21](#) (2)\n\n- [ ] Buy new shoes #shopping\n- [ ] Mail Paul about training schedule\n\n[2022-09-27](#) (1)\n\n- [ ] Get new pillows for mom #shopping\n\n!!! hint \"Counting tasks with subtask\"\n Noticing the (1) on the header of `2022-07-30`? Child tasks belong to their parent task and are not counted separately. Also, they **behave differently** on filtering.\n\n### Child Tasks\n\nA task is considered a **child task** if it is **indented by a tab** and is below an unindented task.\n\n- [ ] clean up the house\n\t- [ ] kitchen\n\t- [x] living room\n\t- [ ] Bedroom [urgent:: true]\n\n\n!!! info \"Children of a bullet point item\"\n While indented tasks under a bulleted list item are, strictly speaking, also child tasks, Dataview will handle them like normal tasks in most cases.\n\nChild Tasks **belong to their parent**. This means if you're querying for tasks, you'll get child tasks as part of their parent back.\n\n~~~\n```dataview\nTASK\n```\n~~~\n\n**Output**\n\n- [ ] clean up the house\n\t- [ ] kitchen\n\t- [x] living room\n\t- [ ] Bedroom [urgent:: true]\n- [ ] Call the insurance about the car\n- [x] Find out the transaction number\n\nThis specifically means that child task will be part of your result set **as long as the parent matches the query** - even if the child task itself doesn't.\n\n~~~\n```dataview\nTASK\nWHERE !completed\n```\n~~~\n\n**Output**\n\n- [ ] clean up the house\n\t- [ ] kitchen\n\t- [x] living room\n\t- [ ] Bedroom [urgent:: true]\n- [ ] Call the insurance about the car\n\nHere, `living room` does **not match** the query, but is included anyway, because its parent `clean up the house` does match.\n\nMind that you'll get individual children tasks back, if the child matches your predicate but the parent doesn't:\n\n~~~\n```dataview\nTASK\nWHERE urgent\n```\n~~~\n\n**Output**\n\n- [ ] Bedroom [urgent:: true]\n\n## CALENDAR\n\nThe `CALENDAR` Query outputs a monthly based calendar where every result is depicted as a dot on it referring date. The `CALENDAR` is the only Query Type that requires an additional information. This additional information needs to be a [date](../annotation/types-of-metadata.md#date) (or unset) on all queried pages.\n\n!!! summary \"`CALENDAR` Query Type\"\n The `CALENDAR` Query Types renders a calendar view where every result is represented by a dot on the given meta data field date.\n\n\n\n~~~\n```dataview\nCALENDAR file.ctime\n```\n~~~\n\n**Output**\n\n\n\nWhile it is possible to use `SORT` and `GROUP BY` in combination with `CALENDAR`, it has **no effect**. Additionally, the calendar query does not render if the given meta data field contains something else than a valid [date](../annotation/types-of-metadata.md#date) (but the field can be empty). To make sure you're only taking valid pages into account, you can filter for valid meta data values:\n\n~~~\n```dataview\nCALENDAR due\nWHERE typeof(due) = \"date\"\n```\n~~~\n"
},
{
"path": "docs/docs/queries/structure.md",
"content": "# Structure of a Query\n\nDataview offers [multiple ways](dql-js-inline.md) to write queries and the syntax differs for each.\n\nThis page provides information on how to write a **Dataview Query Language** (**DQL**) query. If you're interested in how to write Inline Queries, refer to the [inline section on DQL, JS and Inlines](dql-js-inline.md#inline-dql). You'll find more information about **Javascript Queries** on the [Javascript Reference](../api/intro.md).\n\n**DQL** is a SQL like query language for creating different views or calculations on your data. It\nsupports:\n\n- Choosing an **output format** of your output (the [Query Type](./query-types.md))\n- Fetch pages **from a certain [source](../reference/sources.md)**, i.e. a tag, folder or link\n- **Filtering pages/data** by simple operations on fields, like comparison, existence checks, and so on\n- **Transforming fields** for displaying, i.e. with calculations or splitting up multi-value fields\n- **Sorting** results based on fields\n- **Grouping** results based on fields\n- **Limiting** your result count\n\n!!! warning Differences to SQL\n If you are familiar with SQL, please read [Differences to SQL](differences-to-sql.md) to avoid confusing DQL with SQL.\n\nLet's have a look at how we can put DQL to use.\n\n## General Format of a DQL Query\n\nEvery query follows the same structure and consists of\n\n- exactly one **Query Type** with zero, one or many [fields](../annotation/add-metadata.md), depending on query type\n- zero or one **FROM** data commands with one to many [sources](../reference/sources.md)\n- zero to many other **data commands** with one to many [expressions](../reference/expressions.md) and/or other infos depending on the data command\n\nAt a high level, a query conforms to the following pattern:\n\n~~~\n```dataview\n \nFROM \n \n \n ...\n```\n~~~\n\n!!! hint \"Only the Query Type is mandatory.\"\n\nThe following sections will explain the theory in further detail.\n\n## Choose a Output Format\n\nThe output format of a query is determined by its **Query Type**. There are four available:\n\n1. **TABLE**: A table of results with one row per result and one or many columns of field data.\n2. **LIST**: A bullet point list of pages which match the query. You can output one field for each page alongside their file links.\n3. **TASK**: An interactive task list of tasks that match the given query.\n4. **CALENDAR**: A calendar view displaying each hit via a dot on its referred date.\n\nThe Query Type is the **only mandatory command in a query**. Everything else is optional.\n\n!!! attention \"Possibly memory intense examples\"\n Depending on the size of your vault, executing the following examples can take long and even freeze Obsidian in extreme cases. It's recommended that you specify a `FROM` to restrict the query execution to a specific subset of your vaults' files. See next section.\n\n~~~\nLists all pages in your vault as a bullet point list\n```dataview\nLIST\n```\n\nLists all tasks (completed or not) in your vault\n```dataview\nTASK\n```\n\nRenders a Calendar view where each page is represented as a dot on its creation date.\n```dataview\nCALENDAR file.cday\n```\n\nShows a table with all pages of your vault, their field value of due, the files' tags and an average of the values of multi-value field working-hours\n```dataview\nTABLE due, file.tags AS \"tags\", average(working-hours)\n```\n~~~\n\n!!! info \"Read more about the available Query Types and how to use them [here](./query-types.md).\"\n\n## Choose your source\n\nAdditionally to the Query Types, you have several **Data Commands** available that help you restrict, refine, sort or group your query. One of these query commands is the **FROM** statement. `FROM` takes a [source](../reference/sources.md) or a combination of [sources](../reference/sources.md) as an argument and restricts the query to a set of pages that match your source.\n\nIt behaves differently from the other Data Commands: You can add **zero or one** `FROM` data command to your query, right after your Query Type. You cannot add multiple FROM statements and you cannot add it after other Data Commands.\n\n~~~\nLists all pages inside the folder Books and its sub folders\n```dataview\nLIST\nFROM \"Books\"\n```\n\nLists all pages that include the tag #status/open or #status/wip\n```dataview\nLIST\nFROM #status/open OR #status/wip\n```\n\nLists all pages that have either the tag #assignment and are inside folder \"30 School\" (or its sub folders), or are inside folder \"30 School/32 Homeworks\" and are linked on the page School Dashboard Current To Dos\n```dataview\nLIST\nFROM (#assignment AND \"30 School\") OR (\"30 School/32 Homeworks\" AND outgoing([[School Dashboard Current To Dos]]))\n```\n\n~~~\n\n!!! info \"Read more about `FROM` [here](./data-commands.md#from).\"\n\n## Filter, sort, group or limit results\n\nIn addition to the Query Types and the **Data command** `FROM` that's explained above, you have several other **Data Commands** available that help you restrict, refine, sort or group your query results.\n\nAll data commands except the `FROM` command can be used **multiple times in any order** (as long as they come after the Query Type and `FROM`, if `FROM` is used at all). They'll be executed in the order they are written.\n\nAvailable are:\n\n1. **FROM** like explained [above](#choose-your-source).\n2. **WHERE**: Filter notes based on information **inside** notes, the meta data fields.\n3. **SORT**: Sorts your results depending on a field and a direction.\n4. **GROUP BY**: Bundles up several results into one result row per group.\n5. **LIMIT**: Limits the result count of your query to the given number.\n6. **FLATTEN**: Splits up one result into multiple results based on a field or calculation.\n\n~~~\n\nLists all pages that have a metadata field `due` and where `due` is before today\n```dataview\nLIST\nWHERE due AND due < date(today)\n```\n\nLists the 10 most recently created pages in your vault that have the tag #status/open\n```dataview\nLIST\nFROM #status/open\nSORT file.ctime DESC\nLIMIT 10\n```\n\nLists the 10 oldest and incomplete tasks of your vault as an interactive task list, grouped by their containing file and sorted from oldest to newest file.\n```dataview\nTASK\nWHERE !completed\nSORT created ASC\nLIMIT 10\nGROUP BY file.link\nSORT rows.file.ctime ASC\n```\n\n~~~\n\n!!! info \"Find out more about available [data commands](./data-commands.md).\"\n\n## Examples\n\nFollowing are some example queries. Find more examples [here](../resources/examples.md).\n\n~~~\n```dataview\nTASK\n```\n~~~\n\n~~~\n```dataview\nTABLE recipe-type AS \"type\", portions, length\nFROM #recipes\n```\n~~~\n\n~~~\n```dataview\nLIST\nFROM #assignments\nWHERE status = \"open\"\n```\n~~~\n\n~~~\n```dataview\nTABLE file.ctime, appointment.type, appointment.time, follow-ups\nFROM \"30 Protocols/32 Management\"\nWHERE follow-ups\nSORT appointment.time\n```\n~~~\n\n~~~\n```dataview\nTABLE L.text AS \"My lists\"\nFROM \"dailys\"\nFLATTEN file.lists AS L\nWHERE contains(L.author, \"Surname\")\n```\n~~~\n\n~~~\n```dataview\nLIST rows.c\nWHERE typeof(contacts) = \"array\" AND contains(contacts, [[Mr. L]])\nSORT length(contacts)\nFLATTEN contacts as c\nSORT link(c).age ASC\n```\n~~~\n"
},
{
"path": "docs/docs/reference/expressions.md",
"content": "# Expressions\n\nDataview query language **expressions** are anything that yields a value:\n\n- all [fields](../annotation/add-metadata.md)\n- all [literals](./literals.md) \n- and computed values, like `field - 9` of [function calls](./functions.md). \n\nBasically, everything that is not a [Query Type](../queries/query-types.md), nor a [data command](../queries/data-commands.md) is an expression.\n\nFor a very high level summary, following is considered an **expression** in DQL:\n\n```\n# Literals\n1 (number)\ntrue/false (boolean)\n\"text\" (text)\ndate(2021-04-18) (date)\ndur(1 day) (duration)\n[[Link]] (link)\n[1, 2, 3] (list)\n{ a: 1, b: 2 } (object)\n\n# Lambdas\n(x1, x2) => ... (lambda)\n\n# References\nfield (directly refer to a field)\nsimple-field (refer to fields with spaces/punctuation in them like \"Simple Field!\")\na.b (if a is an object, retrieve field named 'b')\na[expr] (if a is an object or array, retrieve field with name specified by expression 'expr')\nf(a, b, ...) (call a function called `f` on arguments a, b, ...)\n\n# Arithmetic\na + b (addition)\na - b (subtraction)\na * b (multiplication)\na / b (division)\na % b (modulo / remainder of division)\n\n# Comparison\na > b (check if a is greater than b)\na < b (check if a is less than b)\na = b (check if a equals b)\na != b (check if a does not equal b)\na <= b (check if a is less than or equal to b)\na >= b (check if a is greater than or equal to b)\n\n# Strings\n\na + b (string concatenation)\na * num (repeat string times)\n\n# Special Operations\n[[Link]].value (fetch `value` from page `Link`)\n```\n\nMore detailed explanations of each follow.\n\n## Expression Types\n\n### Fields as Expressions\n\nThe simplest expression is one that just directly refers to a field. If you have a field called \"duedate\", then you can\nrefer to it directly by name - `duedate`. \n\n~~~\n```dataview\nTABLE duedate, class, field-with-space\n```\n~~~\n\n!!! info \"Field names with spaces and punctuations\"\n If the field name has spaces, punctuation, or other non-letter/number characters, then you can refer to it using Dataview's simplified name, which is all lower case with spaces replaced with \"-\". For example, `this is a field` becomes `this-is-a-field`; `Hello!` becomes `hello`, and so on. Read more under [Field names](../annotation/add-metadata.md#field-names)\n\n### Literals\n\nConstant values - things like `1` or `\"hello\"` or `date(som)` (\"start of month\"). There are literals for each data type\nthat dataview supports; read more about them [here](./literals.md).\n\n~~~\n```dataview\nLIST\nWHERE file.name = \"Scribble\"\n```\n~~~\n\n### Arithmetic\n\nYou can use standard arithmetic operators to combine fields: addition (`+`), subtraction (`-`), multiplication (`*`),\nand division (`/`). For example `field1 + field2` is an expression which computes the sum of the two fields.\n\n~~~\n```dataview\nTABLE start, end, (end - start) - dur(8 h) AS \"Overtime\" \nFROM #work\n```\n\n```dataview\nTABLE hrs / 24 AS \"days\"\nFROM \"30 Projects\"\n```\n~~~\n\n### Comparisons\n\nYou can compare most values using the various comparison operators: `<`, `>`, `<=`, `>=`, `=`, `!=`. This yields a\nboolean true or false value which can be used in `WHERE` blocks in queries.\n\n~~~\n```dataview\nLIST\nFROM \"Games\"\nWHERE price > 10\n```\n\n```dataview\nTASK\nWHERE due <= date(today)\n```\n\n```dataview\nLIST\nFROM #homework\nWHERE status != \"done\"\n```\n~~~\n\n!!! hint \"Comparing different types\"\n Comparing different [data types](../annotation/types-of-metadata.md) with each other can lead to unexpected results. Take the second example: If `due` is not set (neither on page nor task level), it is `null` and `null <= date(today)` returns true, including tasks without any due date. If this is not wanted, add a type check to make sure you're always comparing the same types:\n ~~~\n ```dataview\n TASK\n WHERE typeof(due) = \"date\" AND due <= date(today)\n ```\n ~~~\n Most often, it is sufficient to check if the meta data is available via `WHERE due AND due <= date(today)`, but checking the type is the safer way to get foreseeable results. \n\n### List/Object Indexing\n\nYou can retrieve data from [lists/arrays](../annotation/types-of-metadata.md#list) via the index operator `list[]`, where `` is any computed expression.\nLists are 0-indexed, so the first element is index 0, the second element is index 1, and so on.\nFor example `list(\"A\", \"B\", \"C\")[0] = \"A\"`.\n\nA similar notation style works for [objects](../annotation/types-of-metadata.md#object).\nYou can use `field[\"nestedfield\"]` to reference fields inside an object or otherwise similarly nested.\nFor example, in the YAML defined below, we can reference `previous` via `episode_metadata[\"previous\"]`.\n```yaml\n---\naliases:\n - \"ABC\"\ncurrent_episode: \"S01E03\"\nepisode_metadata:\n previous: \"S01E02\"\n next: \"S01E04\"\n---\n```\n\nYou can also retrieve data from objects (which map text to data values) also using the index operator, where indexes are now strings/text instead of numbers.\nYou can also use the shorthand `object.`, where `` is the name of the value to retrieve.\nFor the previous frontmatter example, we could also use `episode_metadata.previous` to obtain the same value.\n\nIndex expressions also work on objects which have fields that are not directly supported by the query language.\nA good example is `where`, since it is a keyword.\nIf your frontmatter/metadata contains a field `where`, you can reference it via the `row` syntax: `row[\"where\"]`.\nSee the [note in the FAQ](../resources/faq.md#how-do-i-use-fields-with-the-same-name-as-keywords-like-from-where) and [the corresponding issue](https://github.com/blacksmithgu/obsidian-dataview/issues/1164) for further information.\n\n~~~\n```dataview\nTABLE id, episode_metadata.next, aliases[0]\n```\n~~~\n\n### Function Calls\n\nDataview supports various functions for manipulating data, which are described in full in the [functions\ndocumentation](functions.md). They have the general syntax `function(arg1, arg2, ...)` - i.e., `lower(file.name)` or\n`regexmatch(\"A.+\", file.folder)`.\n\n~~~\n```dataview\nLIST\nWHERE contains(file.name, \"WIP\")\n```\n\n```dataview\nLIST\nWHERE string(file.day.year) = split(this.file.name, \"-W\")[0]\n```\n~~~\n\n### Lambdas\n\nLambdas are advanced literals which let you define a function that takes some number of inputs, and produces an output.\nThey have the general form:\n\n```\n(arg1, arg2, arg3, ...) => \n```\n\nLambdas are used in several advanced operators like `reduce` and `map` to allow for complex transformations of data. A\nfew examples:\n\n```\n(x) => x.field (return field of x, often used for map)\n(x, y) => x + y (sum x and y)\n(x) => 2 * x (double x)\n(value) => length(value) = 4 (return true if value is length 4)\n```\n\n~~~\n```dataview\nCALENDAR file.day\nFLATTEN all(map(file.tasks, (x) => x.completed)) AS \"allCompleted\"\nWHERE !allCompleted\n```\n~~~\n\n---\n\n## Type-specific Interactions & Values\n\nMost dataview types have special interactions with operators, or have additional fields that can be retrieved using the\nindex operator. This is true for [dates](../annotation/types-of-metadata.md#date) and [durations](../annotation/types-of-metadata.md#duration) and as well for links. Read more about date and durations on their respective section in [Types of Metadata](../annotation/types-of-metadata.md).\n\n### Links\n\nYou can \"index through\" a link to get values on the corresponding page. For example `[[Assignment Math]].duedate` would get the value\n`duedate` from page `Assignment Math`.\n\n!!! note \"Link Indexing in Expressions\"\n If your link is a field that you defined in an inline field or in front-matter, like `Class:: [[Math]]` and you want to get the field `timetable`, then you\n index into it by writing `Class.timetable`.\n Using `[[Class]].timetable` would look up the page literally called `Class`, and not `Math`!\n"
},
{
"path": "docs/docs/reference/functions.md",
"content": "# Functions\n\nDataview functions provide more advanced ways to manipulate data. You can use functions **in [data commands](../queries/data-commands.md)** (except FROM) to filter or group or use them **as [additional information](../queries/query-types.md)** like TABLE columns or extra output for LIST queries to see your data in a new light.\n\n## How functions work\n\nFunctions are another form of [expression](expressions.md) and can be used everywhere you can use an expression. A function always gives you back a new value and follows this format:\n\n```\nfunctionname(parameter1, parameter2)\n```\n\nParameters are again [expressions](expressions.md) and you can use literals, meta data fields, or even another function as parameter. You'll find out which [data type](../annotation/types-of-metadata.md) your parameters need to have on the documentation of this page. Pay attention to the information inside the function brackets. Parameters in square brackets, i.e. `link(path, [display])` means they are *optional* and can be omitted. Find out more about the default behavior of each function on their explanation.\n\n## Calling functions on lists of values\n\nMost functions can be applied either to single values (like `number`, `string`, `date`, etc.) OR to lists of those\nvalues. If a function is applied to a list, it also returns a list after the function is applied to each element\nin the list. For example:\n\n```js\nlower(\"YES\") = \"yes\"\nlower([\"YES\", \"NO\"]) = [\"yes\", \"no\"]\n\nreplace(\"yes\", \"e\", \"a\") = \"yas\"\nreplace([\"yes\", \"ree\"], \"e\", \"a\") = [\"yas\", \"raa\"]\n```\n\nThis so-called \"function vectorization\" will not be mentioned explicitly on the following definitions and is possible for a wide range of these functionalities implicitly.\n\n## Constructors\n\nConstructors which create values.\n\n### `object(key1, value1, ...)`\n\nCreates a new object with the given keys and values. Keys and values should alternate in the call, and keys should\nalways be strings/text.\n\n```js\nobject() => empty object\nobject(\"a\", 6) => object which maps \"a\" to 6\nobject(\"a\", 4, \"c\", \"yes\") => object which maps a to 4, and c to \"yes\"\n```\n\n### `list(value1, value2, ...)`\n\nCreates a new list with the given values in it. `array` can be used an alias for `list`.\n\n```js\nlist() => empty list\nlist(1, 2, 3) => list with 1, 2, and 3\narray(\"a\", \"b\", \"c\") => list with \"a\", \"b\", and \"c\"\n```\n\n### `date(any)`\n\nParses a date from the provided string, date, or link object, if possible, returning null otherwise.\n\n```js\ndate(\"2020-04-18\") = \ndate([[2021-04-16]]) = \n```\n\n### `date(text, format)`\n\nParses a date from text to luxon `DateTime` with the specified format. Note localized formats might not work.\nUses [Luxon tokens](https://moment.github.io/luxon/#/formatting?id=table-of-tokens).\n\n```js\ndate(\"12/31/2022\", \"MM/dd/yyyy\") => DateTime for December 31th, 2022\ndate(\"210313\", \"yyMMdd\") => DateTime for March 13th, 2021\ndate(\"946778645000\", \"x\") => DateTime for \"2000-01-02T03:04:05\"\n```\n\n### `dur(any)`\n\nParses a duration from the provided string or duration, returning null on failure.\n\n```js\ndur(8 minutes) = <8 minutes>\ndur(\"8 minutes, 4 seconds\") = <8 minutes, 4 seconds>\ndur(dur(8 minutes)) = dur(8 minutes) = <8 minutes>\n```\n\n### `number(string)`\n\nPulls the first number out of the given string, returning it if possible. Returns null if there are no numbers in the\nstring.\n\n```js\nnumber(\"18 years\") = 18\nnumber(34) = 34\nnumber(\"hmm\") = null\n```\n\n### `string(any)`\n\nConverts any value into a \"reasonable\" string representation. This sometimes produces less pretty results than just directly using\nthe value in a query - it is mostly useful for coercing dates, durations, numbers, and so on into strings for\nmanipulation.\n\n```js\nstring(18) = \"18\"\nstring(dur(8 hours)) = \"8 hours\"\nstring(date(2021-08-15)) = \"August 15th, 2021\"\n```\n\n### `link(path, [display])`\n\nConstruct a link object from the given file path or name. If provided with two arguments, the second argument is the\ndisplay name for the link.\n\n```js\nlink(\"Hello\") => link to page named 'Hello'\nlink(\"Hello\", \"Goodbye\") => link to page named 'Hello', displays as 'Goodbye'\n```\n\n### `embed(link, [embed?])`\n\nConvert a link object into an embedded link; support for embedded links is somewhat spotty in Dataview views, though\nembedding of images should work.\n\n```js\nembed(link(\"Hello.png\")) => embedded link to the \"Hello.png\" image, which will render as an actual image.\n```\n\n### `elink(url, [display])`\n\nConstruct a link to an external url (like `www.google.com`). If provided with two arguments, the second\nargument is the display name for the link.\n\n```js\nelink(\"www.google.com\") => link element to google.com\nelink(\"www.google.com\", \"Google\") => link element to google.com, displays as \"Google\"\n```\n\n### `typeof(any)`\n\nGet the type of any object for inspection. Can be used in conjunction with other operators to change behavior based on type.\n\n```js\ntypeof(8) => \"number\"\ntypeof(\"text\") => \"string\"\ntypeof([1, 2, 3]) => \"array\"\ntypeof({ a: 1, b: 2 }) => \"object\"\ntypeof(date(2020-01-01)) => \"date\"\ntypeof(dur(8 minutes)) => \"duration\"\n```\n\n---\n\n## Numeric Operations\n\n### `round(number, [digits])`\n\nRound a number to a given number of digits. If the second argument is not specified, rounds to the nearest whole number;\notherwise, rounds to the given number of digits.\n\n```js\nround(16.555555) = 17\nround(16.555555, 2) = 16.56\n```\n\n### `trunc(number)`\n\nTruncates (\"cuts off\") the decimal point from a number.\n\n```js\ntrunc(12.937) = 12\ntrunc(-93.33333) = -93\ntrunc(-0.837764) = 0\n```\n\n### `floor(number)`\n\nAlways rounds down and returns the largest integer less than or equal to a given number.\nThis means that negative numbers become more negative.\n\n```js\nfloor(12.937) = 12\nfloor(-93.33333) = -94\nfloor(-0.837764) = -1\n```\n\n### `ceil(number)`\n\nAlways rounds up and returns the smallest integer greater than or equal to a given number.\nThis means negative numbers become less negative.\n\n```js\nceil(12.937) = 13\nceil(-93.33333) = -93\nceil(-0.837764) = 0\n```\n\n### `min(a, b, ..)`\n\nCompute the minimum value of a list of arguments, or an array.\n\n```js\nmin(1, 2, 3) = 1\nmin([1, 2, 3]) = 1\n\nmin(\"a\", \"ab\", \"abc\") = \"a\"\n```\n\n### `max(a, b, ...)`\n\nCompute the maximum value of a list of arguments, or an array.\n\n```js\nmax(1, 2, 3) = 3\nmax([1, 2, 3]) = 3\n\nmax(\"a\", \"ab\", \"abc\") = \"abc\"\n```\n\n### `sum(array)`\n\nSums all numeric values in the array. If you have null values in your sum, you can eliminate them via the `nonnull` function.\n\n```js\nsum([1, 2, 3]) = 6\nsum([]) = null\n\nsum(nonnull([null, 1, 8])) = 9\n```\n\n### `product(array)`\n\nCalculates the product of a list of numbers. If you have null values in your average, you can eliminate them via the `nonnull` function.\n\n```js\nproduct([1,2,3]) = 6\nproduct([]) = null\n\nproduct(nonnull([null, 1, 2, 4])) = 8\n```\n\n### `reduce(array, operand)`\n\nA generic function to reduce a list into a single value, valid operands are `\"+\"`, `\"-\"`, `\"*\"`, `\"/\"` and the boolean operands `\"&\"` and `\"|\"`. Note that using `\"+\"` and `\"*\"` equals the `sum()` and `product()` functions, and using `\"&\"` and `\"|\"` matches `all()` and `any()`.\n\n```js\nreduce([100, 20, 3], \"-\") = 77\nreduce([200, 10, 2], \"/\") = 10\nreduce(values, \"*\") = Multiplies every element of values, same as product(values)\nreduce(values, this.operand) = Applies the local field operand to each of the values\nreduce([\"⭐\", 3], \"*\") = \"⭐⭐⭐\", same as \"⭐\" * 3\n\nreduce([1]), \"+\") = 1, has the side effect of reducing the list into a single element\n```\n\n### `average(array)`\n\nComputes the numeric average of numeric values. If you have null values in your average, you can eliminate them via the\n`nonnull` function.\n\n```js\naverage([1, 2, 3]) = 2\naverage([]) = null\n\naverage(nonnull([null, 1, 2])) = 1.5\n```\n\n### `minby(array, function)`\n\nCompute the minimum value of an array, using the provided function.\n\n```js\nminby([1, 2, 3], (k) => k) = 1\nminby([1, 2, 3], (k) => 0 - k) => 3\n\nminby(this.file.tasks, (k) => k.due) => (earliest due)\n```\n\n### `maxby(array, function)`\n\nCompute the maximum value of an array, using the provided function.\n\n```js\nmaxby([1, 2, 3], (k) => k) = 3\nmaxby([1, 2, 3], (k) => 0 - k) => 1\n\nmaxby(this.file.tasks, (k) => k.due) => (latest due)\n```\n\n--\n\n## Objects, Arrays, and String Operations\n\nOperations that manipulate values inside of container objects.\n\n### `contains()` and friends\n\nFor a quick summary, here are some examples:\n\n```js\ncontains(\"Hello\", \"Lo\") = false\ncontains(\"Hello\", \"lo\") = true\n\nicontains(\"Hello\", \"Lo\") = true\nicontains(\"Hello\", \"lo\") = true\n\necontains(\"Hello\", \"Lo\") = false\necontains(\"Hello\", \"lo\") = true\necontains([\"this\",\"is\",\"example\"], \"ex\") = false\necontains([\"this\",\"is\",\"example\"], \"is\") = true\n```\n\n#### `contains(object|list|string, value)`\n\nChecks if the given container type has the given value in it. This function behave slightly differently based on whether\nthe first argument is an object, a list, or a string.\nThis function is case-sensitive.\n\n- For objects, checks if the object has a key with the given name. For example,\n ```\n contains(file, \"ctime\") = true\n contains(file, \"day\") = true (if file has a date in its title, false otherwise)\n ```\n- For lists, checks if any of the array elements equals the given value. For example,\n ```\n contains(list(1, 2, 3), 3) = true\n contains(list(), 1) = false\n ```\n- For strings, checks if the given value is a substring (i.e., inside) the string.\n ```\n contains(\"hello\", \"lo\") = true\n contains(\"yes\", \"no\") = false\n ```\n\n#### `icontains(object|list|string, value)`\n\nCase insensitive version of `contains()`.\n\n#### `econtains(object|list|string, value)`\n\n\"Exact contains\" checks if the exact match is found in the string/list.\nThis function is case sensitive.\n\n- For strings, it behaves exactly like [`contains()`](#containsobjectliststring-value).\n ```\n econtains(\"Hello\", \"Lo\") = false\n econtains(\"Hello\", \"lo\") = true\n ```\n\n- For lists, it checks if the exact word is in the list.\n ```\n econtains([\"These\", \"are\", \"words\"], \"word\") = false\n econtains([\"These\", \"are\", \"words\"], \"words\") = true\n ```\n\n- For objects, it checks if the exact key name is present in the object. It does **not** do recursive checks.\n ```\n econtains({key:\"value\", pairs:\"here\"}, \"here\") = false\n econtains({key:\"value\", pairs:\"here\"}, \"key\") = true\n econtains({key:\"value\", recur:{recurkey: \"val\"}}, \"value\") = false\n econtains({key:\"value\", recur:{recurkey: \"val\"}}, \"Recur\") = false\n econtains({key:\"value\", recur:{recurkey: \"val\"}}, \"recurkey\") = false\n ```\n\n### `containsword(list|string, value)`\n\nChecks if `value` has an exact word match in `string` or `list`.\nThis is case insensitive.\nThe outputs are different for different types of input, see examples.\n\n- For strings, it checks if the word is present in the given string.\n ```\n containsword(\"word\", \"word\") = true\n containsword(\"word\", \"Word\") = true\n containsword(\"words\", \"Word\") = false\n containsword(\"Hello there!\", \"hello\") = true\n containsword(\"Hello there!\", \"HeLLo\") = true\n containsword(\"Hello there chaps!\", \"chap\") = false\n containsword(\"Hello there chaps!\", \"chaps\") = true\n ```\n\n- For lists, it returns a list of booleans indicating if the word's exact case insensitive match was found.\n ```\n containsword([\"I have no words.\", \"words\"], \"Word\") = [false, false]\n containsword([\"word\", \"Words\"], \"Word\") = [true, false]\n containsword([\"Word\", \"Words in word\"], \"WORD\") = [true, true]\n ```\n\n### `extract(object, key1, key2, ...)`\n\nPulls multiple fields out of an object, creating a new object with just those fields.\n\n```\nextract(file, \"ctime\", \"mtime\") = object(\"ctime\", file.ctime, \"mtime\", file.mtime)\nextract(object(\"test\", 1)) = object()\n```\n\n### `sort(list)`\n\nSorts a list, returning a new list in sorted order.\n\n```\nsort(list(3, 2, 1)) = list(1, 2, 3)\nsort(list(\"a\", \"b\", \"aa\")) = list(\"a\", \"aa\", \"b\")\n```\n\n### `reverse(list)`\n\nReverses a list, returning a new list in reversed order.\n\n```\nreverse(list(1, 2, 3)) = list(3, 2, 1)\nreverse(list(\"a\", \"b\", \"c\")) = list(\"c\", \"b\", \"a\")\n```\n\n### `length(object|array)`\n\nReturns the number of fields in an object, or the number of entries in an array.\n\n```\nlength([]) = 0\nlength([1, 2, 3]) = 3\nlength(object(\"hello\", 1, \"goodbye\", 2)) = 2\n```\n\n### `nonnull(array)`\n\nReturn a new array with all null values removed.\n\n```\nnonnull([]) = []\nnonnull([null, false]) = [false]\nnonnull([1, 2, 3]) = [1, 2, 3]\n```\n\n### `firstvalue(array)`\n\nReturn the first non-null value from the array, as a single element. This can be used to pick the first defined field in the children of a task/list item, like in `firstvalue(children.myField)`.\n\n```js\nfirstvalue([null, 1, 2]) => 1\nfirstvalue(children.myField) => If children.myField equals [null, null, \"myValue\", null], it would return \"myValue\"\n```\n\n### `all(array)`\n\nReturns `true` only if ALL values in the array are truthy. You can also pass multiple arguments to this function, in\nwhich case it returns `true` only if all arguments are truthy.\n\n```\nall([1, 2, 3]) = true\nall([true, false]) = false\nall(true, false) = false\nall(true, true, true) = true\n```\n\nYou can pass a function as second argument to return only true if all elements in the array matches the predicate.\n\n```\nall([1, 2, 3], (x) => x > 0) = true\nall([1, 2, 3], (x) => x > 1) = false\nall([\"apple\", \"pie\", 3], (x) => typeof(x) = \"string\") = false\n```\n\n### `any(array)`\n\nReturns `true` if ANY of the values in the array are truthy. You can also pass multiple arguments to this function, in\nwhich case it returns `true` if any of the arguments are truthy.\n\n```\nany(list(1, 2, 3)) = true\nany(list(true, false)) = true\nany(list(false, false, false)) = false\nany(true, false) = true\nany(false, false) = false\n```\n\nYou can pass a function as second argument to return only true if any element in the array matches the predicate.\n\n```\nany(list(1, 2, 3), (x) => x > 2) = true\nany(list(1, 2, 3), (x) => x = 0) = false\n```\n\n### `none(array)`\n\nReturns `true` if NONE of the values in the array are truthy.\n\n```\nnone([]) = true\nnone([false, false]) = true\nnone([false, true]) = false\nnone([1, 2, 3]) = false\n```\n\nYou can pass a function as second argument to return only true if none of the elements in the array matches the predicate.\n\n```\nnone([1, 2, 3], (x) => x = 0) = true\nnone([true, true], (x) => x = false) = true\nnone([\"Apple\", \"Pi\", \"Banana\"], (x) => startswith(x, \"A\")) = false\n```\n\n### `join(array, [delimiter])`\n\nJoins elements in an array into a single string (i.e., rendering them all on the same line). If provided with a second\nargument, then each element will be separated by the given separator.\n\n```\njoin(list(1, 2, 3)) = \"1, 2, 3\"\njoin(list(1, 2, 3), \" \") = \"1 2 3\"\njoin(6) = \"6\"\njoin(list()) = \"\"\n```\n\n### `filter(array, predicate)`\n\nFilters elements in an array according to the predicate, returning a new list of the elements which matched.\n\n```js\nfilter([1, 2, 3], (x) => x >= 2) = [2, 3]\nfilter([\"yes\", \"no\", \"yas\"], (x) => startswith(x, \"y\")) = [\"yes\", \"yas\"]\n```\n\n### `unique(array)`\n\nCreates a new array with only unique values. \n\n```js\nunique([1, 3, 7, 3, 1]) => [1, 3, 7]\n```\n\n### `map(array, func)`\n\nApplies the function to each element in the array, returning a list of the mapped results.\n\n```js\nmap([1, 2, 3], (x) => x + 2) = [3, 4, 5]\nmap([\"yes\", \"no\"], (x) => x + \"?\") = [\"yes?\", \"no?\"]\n```\n\n### `flat(array, [depth])`\n\nConcatenates sub-levels of the array to the desired depth. Default is 1 level, but it can\nconcatenate multiple levels. E.g. Can be used to reduce array depth on `rows` lists after\ndoing `GROUP BY`.\n\n```js\nflat(list(1, 2, 3, list(4, 5), 6)) => list(1, 2, 3, 4, 5, 6)\nflat(list(1, list(21, 22), list(list (311, 312, 313))), 4) => list(1, 21, 22, 311, 312, 313)\nflat(rows.file.outlinks)) => All the file outlinks at first level in output\n```\n\n### `slice(array, [start, [end]])`\n\nReturns a shallow copy of a portion of an array into a new array object selected from `start`\nto `end` (`end` not included) where `start` and `end` represents the index of items in that array.\n\n```js\nslice([1, 2, 3, 4, 5], 3) = [4, 5] => All items from given position, 0 as first\nslice([\"ant\", \"bison\", \"camel\", \"duck\", \"elephant\"], 0, 2) = [\"ant\", \"bison\"] => First two items\nslice([1, 2, 3, 4, 5], -2) = [4, 5] => counts from the end, last two items\nslice(someArray) => a copy of someArray\n```\n\n---\n\n## String Operations\n\n### `regextest(pattern, string)`\n\nChecks if the given regex pattern can be found in the string (using the JavaScript regex engine).\n\n```js\nregextest(\"\\w+\", \"hello\") = true\nregextest(\".\", \"a\") = true\nregextest(\"yes|no\", \"maybe\") = false\nregextest(\"what\", \"what's up dog?\") = true\n```\n\n### `regexmatch(pattern, string)`\n\nChecks if the given regex pattern matches the *entire* string, using the JavaScript regex engine.\nThis differs from `regextest` in that regextest can match just parts of the text.\n\n```js\nregexmatch(\"\\w+\", \"hello\") = true\nregexmatch(\".\", \"a\") = true\nregexmatch(\"yes|no\", \"maybe\") = false\nregexmatch(\"what\", \"what's up dog?\") = false\n```\n\n### `regexreplace(string, pattern, replacement)`\n\nReplaces all instances where the *regex* `pattern` matches in `string`, with `replacement`. This uses the JavaScript\nreplace method under the hood, so you can use special characters like `$1` to refer to the first capture group, and so on.\n\n```js\nregexreplace(\"yes\", \"[ys]\", \"a\") = \"aea\"\nregexreplace(\"Suite 1000\", \"\\d+\", \"-\") = \"Suite -\"\n```\n\n### `replace(string, pattern, replacement)`\n\nReplace all instances of `pattern` in `string` with `replacement`.\n\n```js\nreplace(\"what\", \"wh\", \"h\") = \"hat\"\nreplace(\"The big dog chased the big cat.\", \"big\", \"small\") = \"The small dog chased the small cat.\"\nreplace(\"test\", \"test\", \"no\") = \"no\"\n```\n\n### `lower(string)`\n\nConvert a string to all lower case.\n\n```js\nlower(\"Test\") = \"test\"\nlower(\"TEST\") = \"test\"\n```\n\n### `upper(string)`\n\nConvert a string to all upper case.\n\n```js\nupper(\"Test\") = \"TEST\"\nupper(\"test\") = \"TEST\"\n```\n\n### `split(string, delimiter, [limit])`\n\nSplit a string on the given delimiter string. If a third argument is provided, it limits the number of splits that occur. The delimiter string is interpreted as a regular expression. If there are capture groups in the delimiter, matches are spliced into the result array, and non-matching captures are empty strings.\n\n\n```js\nsplit(\"hello world\", \" \") = list(\"hello\", \"world\")\nsplit(\"hello world\", \"\\s\") = list(\"hello\", \"world\")\nsplit(\"hello there world\", \" \", 2) = list(\"hello\", \"there\")\nsplit(\"hello there world\", \"(t?here)\") = list(\"hello \", \"there\", \" world\")\nsplit(\"hello there world\", \"( )(x)?\") = list(\"hello\", \" \", \"\", \"there\", \" \", \"\", \"world\")\n```\n\n### `startswith(string, prefix)`\n\nChecks if a string starts with the given prefix.\n\n```js\nstartswith(\"yes\", \"ye\") = true\nstartswith(\"path/to/something\", \"path/\") = true\nstartswith(\"yes\", \"no\") = false\n```\n\n### `endswith(string, suffix)`\n\nChecks if a string ends with the given suffix.\n\n```js\nendswith(\"yes\", \"es\") = true\nendswith(\"path/to/something\", \"something\") = true\nendswith(\"yes\", \"ye\") = false\n```\n\n### `padleft(string, length, [padding])`\n\nPads a string up to the desired length by adding padding on the left side. If you omit the padding character, spaces\nwill be used by default.\n\n```js\npadleft(\"hello\", 7) = \" hello\"\npadleft(\"yes\", 5, \"!\") = \"!!yes\"\n```\n\n### `padright(string, length, [padding])`\n\nEquivalent to `padleft`, but pads to the right instead.\n\n```js\npadright(\"hello\", 7) = \"hello \"\npadright(\"yes\", 5, \"!\") = \"yes!!\"\n```\n\n### `substring(string, start, [end])`\n\nTake a slice of a string, starting at `start` and ending at `end` (or the end of the string if unspecified).\n\n```js\nsubstring(\"hello\", 0, 2) = \"he\"\nsubstring(\"hello\", 2, 4) = \"ll\"\nsubstring(\"hello\", 2) = \"llo\"\nsubstring(\"hello\", 0) = \"hello\"\n```\n\n### `truncate(string, length, [suffix])`\n\nTruncate a string to be at most the given length, including the `suffix` (which defaults to `...`). Generally useful\nto cut off long text in tables.\n\n```js\ntruncate(\"Hello there!\", 8) = \"Hello...\"\ntruncate(\"Hello there!\", 8, \"/\") = \"Hello t/\"\ntruncate(\"Hello there!\", 10) = \"Hello t...\"\ntruncate(\"Hello there!\", 10, \"!\") = \"Hello the!\"\ntruncate(\"Hello there!\", 20) = \"Hello there!\"\n```\n\n## Utility Functions\n\n### `default(field, value)`\n\nIf `field` is null, return `value`; otherwise return `field`. Useful for replacing null values with defaults. For example, to show projects which haven't been completed yet, use `\"incomplete\"` as their default value:\n\n```js\ndefault(dateCompleted, \"incomplete\")\n```\n\nDefault is vectorized in both arguments; if you need to use default explicitly on a list argument, use `ldefault`, which\nis the same as default but is not vectorized.\n\n```js\ndefault(list(1, 2, null), 3) = list(1, 2, 3)\nldefault(list(1, 2, null), 3) = list(1, 2, null)\n```\n\n### `display()`\n\nDisplay function converts the input into a string representation while trying to\npreserve the display property of data types.\nThis means that links and urls will be replaced by their display value.\n\n\n```js\ndisplay(\"Hello World\") = \"Hello World\"\ndisplay(\"**Hello** World\") = \"Hello World\"\ndisplay(\"[Hello](https://example.com) [[World]]\") = \"Hello World\"\ndisplay(link(\"path/to/file.md\")) = \"file\"\ndisplay(link(\"path/to/file.md\", \"displayname\")) = \"displayname\"\ndisplay(date(\"2024-11-18\")) = \"November 18, 2024\"\ndisplay(list(\"Hello\", \"World\")) = \"Hello, World\"\n```\n\n### `choice(bool, left, right)`\n\nA primitive if statement - if the first argument is truthy, returns left; otherwise, returns right.\n\n```js\nchoice(true, \"yes\", \"no\") = \"yes\"\nchoice(false, \"yes\", \"no\") = \"no\"\nchoice(x > 4, y, z) = y if x > 4, else z\n```\n\n### `hash(seed, [text], [variant])`\n\nGenerate a hash based on the `seed`, and the optional extra `text` or a variant `number`. The function\ngenerates a fixed number based on the combination of these parameters, which can be used to randomize\nthe sort order of files or lists/tasks. If you choose a `seed` based on a date, i.e. \"2024-03-17\",\nor another timestamp, i.e. \"2024-03-17 19:13\", you can make the \"randomness\" be fixed\nrelated to that timestamp. `variant` is a number, which in some cases is needed to make the combination of\n`text` and `variant` become unique.\n\n```js\nhash(dateformat(date(today), \"YYYY-MM-DD\"), file.name) = ... A unique value for a given date in time\nhash(dateformat(date(today), \"YYYY-MM-DD\"), file.name, position.start.line) = ... A unique \"random\" value in a TASK query\n```\n\nThis function can be used in a `SORT` statement to randomize the order. If you're using a `TASK` query,\nsince the file name could be the same for multiple tasks, you can add some number like the starting line\nnumber (as shown above) to make it a unique combination. If using something like `FLATTEN file.lists as item`,\nthe similar addition would be to do `item.position.start.line` as the last parameter.\n\n### `striptime(date)`\n\nStrip the time component of a date, leaving only the year, month, and day. Good for date comparisons if you don't care\nabout the time.\n\n```js\nstriptime(file.ctime) = file.cday\nstriptime(file.mtime) = file.mday\n```\n\n### `dateformat(date|datetime, string)`\n\nFormat a Dataview date using a formatting string. Uses [Luxon tokens](https://moment.github.io/luxon/#/formatting?id=table-of-tokens).\n\n```js\ndateformat(file.ctime,\"yyyy-MM-dd\") = \"2022-01-05\"\ndateformat(file.ctime,\"HH:mm:ss\") = \"12:18:04\"\ndateformat(date(now),\"x\") = \"1407287224054\"\ndateformat(file.mtime,\"ffff\") = \"Wednesday, August 6, 2014, 1:07 PM Eastern Daylight Time\"\n```\n\n**Note:** `dateformat()` returns a string, not a date, so you can't compare it against the result from a call to `date()` or a variable like `file.day` which already is a date. To make those comparisons you can format both arguments.\n\n### `durationformat(duration, string)`\n\nFormat a Dataview duration using a formatting string.\nAnything inside single quotes will not be treated as a token and\ninstead will be shown in the output as written. See examples.\n\nYou may use these tokens:\n\n- `S` for milliseconds\n- `s` for seconds\n- `m` for minutes\n- `h` for hours\n- `d` for days\n- `w` for weeks\n- `M` for months\n- `y` for years\n\n```js\ndurationformat(dur(\"3 days 7 hours 43 seconds\"), \"ddd'd' hh'h' ss's'\") = \"003d 07h 43s\"\ndurationformat(dur(\"365 days 5 hours 49 minutes\"), \"yyyy ddd hh mm ss\") = \"0001 000 05 49 00\"\ndurationformat(dur(\"2000 years\"), \"M months\") = \"24000 months\"\ndurationformat(dur(\"14d\"), \"s 'seconds'\") = \"1209600 seconds\"\n```\n\n### `currencyformat(number, [currency])`\n\nPresents the number depending on your current locale, according to the `currency` code, from [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes).\n\n```\nnumber = 123456.789\ncurrencyformat(number, \"EUR\") = €123,456.79 in locale: en_US)\ncurrencyformat(number, \"EUR\") = 123.456,79 € in locale: de_DE)\ncurrencyformat(number, \"EUR\") = € 123 456,79 in locale: nb)\n```\n\n### `localtime(date)`\n\nConverts a date in a fixed timezone to a date in the current timezone.\n\n### `meta(link)`\n\nGet an object containing metadata of a link. When you access a property on a link what you get back is the property\nvalue from the linked file. The `meta` function makes it possible to access properties of the link itself.\n\nThere are several properties on the object returned by `meta`:\n\n#### `meta(link).display`\n\nGet the display text of a link, or null if the link does not have defined display text.\n\n```js\nmeta([[2021-11-01|Displayed link text]]).display = \"Displayed link text\"\nmeta([[2021-11-01]]).display = null\n```\n\n#### `meta(link).embed`\n\nTrue or false depending on whether the link is an embed. Those are links that begin with an exclamation mark, like\n`![[Some Link]]`.\n\n#### `meta(link).path`\n\nGet the path portion of a link.\n\n```js\nmeta([[My Project]]).path = \"My Project\"\nmeta([[My Project#Next Actions]]).path = \"My Project\"\nmeta([[My Project#^9bcbe8]]).path = \"My Project\"\n```\n\n#### `meta(link).subpath`\n\nGet the subpath of a link. For links to a heading within a file the subpath will be the text of the heading. For links\nto a block the subpath will be the block ID. If neither of those cases applies then the subpath will be null.\n\n```js\nmeta([[My Project#Next Actions]]).subpath = \"Next Actions\"\nmeta([[My Project#^9bcbe8]]).subpath = \"9bcbe8\"\nmeta([[My Project]]).subpath = null\n```\n\nThis can be used to select tasks under specific headings.\n\n````\n```dataview\ntask\nwhere meta(section).subpath = \"Next Actions\"\n```\n````\n\n#### `meta(link).type`\n\nHas the value \"file\", \"header\", or \"block\" depending on whether the link links to an entire file, a heading within\na file, or to a block within a file.\n\n```js\nmeta([[My Project]]).type = \"file\"\nmeta([[My Project#Next Actions]]).type = \"header\"\nmeta([[My Project#^9bcbe8]]).type = \"block\"\n```\n"
},
{
"path": "docs/docs/reference/literals.md",
"content": "# Literals\n\nDataview query language *literals* are **expressions** which represent constant values like a text (`\"Science\"`) or a number (`2021`). They can be used as part as [functions](functions.md) or of [expressions like comparison](./expressions.md). Some examples of [Queries](../queries/structure.md) that use **literals**:\n\n~~~\n\nLiteral (number) 2022 used in a comparison\n```dataview\nLIST\nWHERE file.day.year = 2022\n```\n\nLiteral (text) \"Math\" used in a function call\n```dataview\nLIST\nWHERE contains(file.name, \"Math\")\n```\n\nLiteral (link) [[Study MOC]] used as a source\n```dataview\nLIST\nFROM [[Study MOC]]\n```\n\nLiteral (date) date(yesterday) used in a comparison\n```dataview\nTASK\nWHERE !completed AND file.day = date(yesterday)\n```\n\nLiteral (duration) dur(2 days) used in a comparison\n```dataview\nLIST\nWHERE end - start > dur(2 days)\n```\n~~~\n\n!!! summary \"Literals\"\n Literals are **static values** that can be used as part of the Dataview Query Language (DQL), i.e. for comparisons.\n\nThe following is an extensive, but non-exhaustive list of possible literals in DQL.\n\n### General\nLiteral|Description\n-|-\n`0`|The number zero\n`1337`|The positive number 1337\n`-200`| The negative number -200\n`\"The quick brown fox jumps over the lazy dog\"`| Text (sometimes referred to as \"string\")\n`[[Science]]`|A link to the file named \"Science\"\n`[[]]`| A link to the current file\n`[1, 2, 3]`|A list of numbers 1, 2, and 3\n`[[1, 2],[3, 4]]`|A list of list [1, 2] and [3, 4]\n`{ a: 1, b: 2 }`| An object with keys a and b, whereas a has value 1, b 2. |\n`date(2021-07-14)`| A date (read more below) |\n`dur(2 days 4 hours)` | A duration (read more below) | \n\n!!! attention \"Literals as field values\"\n Literals are only interpreted this way when used inside a Query, not when used as a meta data value. For possible values and their data types for fields, please refer to [Types of Metadata](../annotation/types-of-metadata.md).\n\n### Dates\n\nWhenever you use a [field value in Date ISO format](../annotation/types-of-metadata.md#date), you'll need to compare these fields against date objects. Dataview provides some shorthands for common use cases like tomorrow, start of current week etc. Please note that `date()` is also a [function](functions.md#dateany), which can be called on **text** to extract dates.\n\nLiteral|Description\n-|-\n`date(2021-11-11)`|A date, November 11th, 2021\n`date(2021-09-20T20:17)`| A date, September 20th, 2021 at 20:17\n`date(today)`|A date representing the current date\n`date(now)`|A date representing the current date and time\n`date(tomorrow)`|A date representing tomorrow's date\n`date(yesterday)`|A date representing yesterday's date\n`date(sow)`|A date representing the start of the current week\n`date(eow)`|A date representing the end of the current week\n`date(som)`|A date representing the start of the current month\n`date(eom)`|A date representing the end of the current month\n`date(soy)`|A date representing the start of the current year\n`date(eoy)`|A date representing the end of the current year\n\n### Durations\n\nDurations are representatives of a time span. You can either [define them directly](../annotation/types-of-metadata.md#duration) or create them due to [calculating with dates](../annotation/types-of-metadata.md#duration), and use these for i.e. comparisons.\n\n#### Seconds\nLiteral|Description\n-|-\n`dur(1 s)`|one second\n`dur(3 s)`|three seconds\n`dur(1 sec)`|one second\n`dur(3 secs)`|three seconds\n`dur(1 second)`|one second\n`dur(3 seconds)`|three seconds\n\n#### Minutes\nLiteral|Description\n-|-\n`dur(1 m)`|one minute\n`dur(3 m)`|three minutes\n`dur(1 min)`|one minute\n`dur(3 mins)`|three minutes\n`dur(1 minute)`|one minute\n`dur(3 minutes)`|three minutes\n\n#### Hours\nLiteral|Description\n-|-\n`dur(1 h)`|one hour\n`dur(3 h)`|three hours\n`dur(1 hr)`|one hour\n`dur(3 hrs)`|three hours\n`dur(1 hour)`|one hour\n`dur(3 hours)`|three hours\n\n#### Days\nLiteral|Description\n-|-\n`dur(1 d)`|one day\n`dur(3 d)`|three days\n`dur(1 day)`|one day\n`dur(3 days)`|three days\n\n#### Weeks\nLiteral|Description\n-|-\n`dur(1 w)`|one week\n`dur(3 w)`|three weeks\n`dur(1 wk)`|one week\n`dur(3 wks)`|three weeks\n`dur(1 week)`|one week\n`dur(3 weeks)`|three weeks\n\n#### Months\nLiteral|Description\n-|-\n`dur(1 mo)`|one month\n`dur(3 mo)`|three month\n`dur(1 month)`|one month\n`dur(3 months)`|three months\n\n#### Years\nLiteral|Description\n-|-\n`dur(1 yr)`|one year\n`dur(3 yrs)`|three years\n`dur(1 year)`|one year\n`dur(3 years)`|three years\n\n#### Combinations\nLiteral|Description\n-|-\n`dur(1 s, 2 m, 3 h)`|three hours, two minutes, and one second\n`dur(1 s 2 m 3 h)`|three hours, two minutes, and one second\n`dur(1s 2m 3h)`|three hours, two minutes, and one second\n`dur(1second 2min 3h)`|three hours, two minutes, and one second\n"
},
{
"path": "docs/docs/reference/sources.md",
"content": "# Sources\n\nA dataview **source** is something that identifies a set of files, tasks, or other data. Sources are indexed internally by\nDataview, so they are fast to query. The most prominent use of sources is the [FROM data command](../../queries/data-commands.md#from). They are also used in various JavaScript API query calls.\n\n## Types of Sources\n\nDataview currently supports **four source types**.\n\n### Tags\n\nSources of the form `#tag`. These match all files / sections / tasks with the given tag.\n\n~~~\n```dataview\nLIST\nFROM #homework\n```\n~~~\n\n### Folders\n\nSources of the form `\"folder\"`. These match all files / sections / tasks contained in the given folder and its sub folders. The full vault path is expected instead of just the folder name. Note that trailing slashes are not supported, i.e. `\"Path/To/Folder/\"` will not work but `\"Path/To/Folder\"` will.\n\n~~~\n```dataview\nTABLE file.ctime, status\nFROM \"projects/brainstorming\"\n```\n~~~\n\n\n### Specific Files\n\nYou can select from a specific file by specifying it's full path: `\"folder/File\"`.\n\n- If you have both a file and a folder with the exact same path, Dataview will prefer the folder. You can force it to read from the file by specifying an extension: `folder/File.md`.\n\n~~~\n```dataview\nLIST WITHOUT ID next-in-line\nFROM \"30 Hobbies/Games/Dashboard\"\n```\n~~~\n\n\n### Links\n\n You can either select links **to** a file, or all links **from** a file.\n \n- To obtain all pages which link **to** `[[note]]`, use `[[note]]`.\n- To obtain all pages which link **from** `[[note]]` (i.e., all the links in that file), use `outgoing([[note]])`.\n- You can implicitly reference the current file via `[[#]]` or `[[]]`, i.e. `[[]]` lets you query from all files linking to the current file.\n\n~~~\n```dataview\nLIST\nFROM [[]]\n```\n\n```dataview\nLIST\nFROM outgoing([[Dashboard]])\n```\n~~~\n\n\n## Combining Sources\n\nYou can compose these filters in order to get more advanced sources using `and` and `or`.\n\n- For example, `#tag and \"folder\"` will return all pages in `folder` and with `#tag`.\n- Querying from `#food and !#fastfood` will only return pages that contain `#food` but does not contain `#fastfood`.\n- `[[Food]] or [[Exercise]]` will give any pages which link to `[[Food]]` OR `[[Exercise]]`.\n\nIf you have complex queries where grouping or precedence matters, you can use parenthesis to logically group them:\n\n- `#tag and (\"folder\" or #other-tag)`\n- `(#tag1 or #tag2) and (#tag3 or #tag4)`\n\n\n"
},
{
"path": "docs/docs/resources/develop-against-dataview.md",
"content": "# Developing Against Dataview\n\nDataview includes a high-level plugin-facing API as well as TypeScript definitions and a utility library; to install it,\nsimply use:\n\n```bash\nnpm install -D obsidian-dataview\n```\n\nTo verify that it is the correct version installed, do `npm list obsidian-dataview`. If that fails to report the latest version, which currently is 0.5.64, you can do:\n\n```bash\nnpm install obsidian-dataview@0.5.64\n```\n\n**Note**: If [Git](http://git-scm.com/) is not already installed on your local system, you will need to install it first. You may need to restart your device to complete the Git installation before you can install the Dataview API.\n\n##### Accessing the Dataview API\n\nYou can use the `getAPI()` function to obtain the Dataview Plugin API; this returns a `DataviewApi` object which\nprovides various utilities, including rendering dataviews, checking dataview's version, hooking into the dataview event\nlife cycle, and querying dataview metadata.\n\n```ts\nimport { getAPI } from \"obsidian-dataview\";\n\nconst api = getAPI();\n```\n\nFor full API definitions available, check\n[index.ts](https://github.com/blacksmithgu/obsidian-dataview/blob/master/src/index.ts) or the plugin API definition [plugin-api.ts](https://github.com/blacksmithgu/obsidian-dataview/blob/master/src/api/plugin-api.ts).\n\n##### Binding to Dataview Events\n\nYou can bind to dataview metadata events, which fire on all file updates and changes, via:\n\n\n```ts\nplugin.registerEvent(plugin.app.metadataCache.on(\"dataview:index-ready\", () => {\n ...\n});\n\nplugin.registerEvent(plugin.app.metadataCache.on(\"dataview:metadata-change\",\n (type, file, oldPath?) => { ... }));\n```\n\nFor all events hooked on MetadataCache, check [index.ts](https://github.com/blacksmithgu/obsidian-dataview/blob/master/src/index.ts).\n\n##### Value Utilities\n\nYou can access various type utilities which let you check the types of objects and compare them via `Values`:\n\n~~~ts\nimport { getAPI, Values } from \"obsidian-dataview\";\n\nconst field = getAPI(plugin.app)?.page('sample.md').field;\nif (!field) return;\n\nif (Values.isHtml(field)) // do something\nelse if (Values.isLink(field)) // do something\n// ...\n~~~\n"
},
{
"path": "docs/docs/resources/examples.md",
"content": "# Examples\n\nA small collection of simple usages of the dataview query language.\n\n---\n\nShow all games in the games folder, sorted by rating, with some metadata:\n\n=== \"Query\"\n ```sql\n TABLE\n time-played AS \"Time Played\",\n length AS \"Length\",\n rating AS \"Rating\"\n FROM \"games\"\n SORT rating DESC\n ```\n=== \"Output\"\n |File|Time Played|Length|Rating|\n |-|-|-|-|\n |[Outer Wilds](#)|November 19th - 21st, 2020|15h|9.5|\n |[Minecraft](#)|All the time.|2000h|9.5|\n |[Pillars of Eternity 2](#)|August - October 2019|100h|9|\n\n---\n\nList games which are MOBAs or CRPGs.\n\n=== \"Query\"\n ``` sql\n LIST FROM #games/mobas OR #games/crpg\n ```\n=== \"Output\"\n - [League of Legends](#)\n - [Pillars of Eternity 2](#)\n\n---\n\nList all tasks in un-completed projects:\n\n=== \"Query\"\n ``` sql\n TASK FROM \"dataview\"\n ```\n=== \"Output\"\n [dataview/Project A](#)\n\n - [ ] I am a task.\n - [ ] I am another task.\n\n [dataview/Project A](#)\n\n - [ ] I could be a task, though who knows.\n - [X] Determine if this is a task.\n - [X] I'm a finished task.\n\n---\n\nList all of the files in the `books` folder, sorted by the last time you modified the file:\n\n=== \"Query\"\n ```sql\n TABLE file.mtime AS \"Last Modified\"\n FROM \"books\"\n SORT file.mtime DESC\n ```\n=== \"Output\"\n |File|Last Modified|\n |-|-|\n |[Atomic Habits](#)|11:06 PM - August 07, 2021|\n |[Can't Hurt Me](#)|10:58 PM - August 07, 2021|\n |[Deep Work](#)|10:52 PM - August 07, 2021|\n\n---\n\nList all files which have a date in their title (of the form `yyyy-mm-dd`), and list them by date order.\n\n=== \"Query\"\n ```sql\n LIST file.day WHERE file.day\n SORT file.day DESC\n ```\n=== \"Output\"\n - [2021-08-07](#): August 07, 2021\n - [2020-08-10](#): August 10, 2020\n"
},
{
"path": "docs/docs/resources/faq.md",
"content": "# Frequently Asked Questions\n\nA collection of frequently asked questions for Dataview queries and the expression language.\n\n### How do I use fields with the same name as keywords (like \"from\", \"where\")?\n\nDataview provides a special \"fake\" field called `row` which can be indexed into to obtain fields which conflict with\nDataview keywords:\n\n```javascript\nrow.from /* Same as \"from\" */\nrow.where /* Same as \"where\" */\n```\n\n\n### How do I access fields with spaces in the name?\n\nThere are two ways:\n\n1. Use the normalized Dataview name for such a field - just convert the name to lowercase and replace whitespace with\n dashes (\"-\"). Something like `Field With Space In It` becomes `field-with-space-in-it`.\n2. Use the implicit `row` field:\n ```javascript\n row[\"Field With Space In It\"]\n ```\n\n### Do you have a list of resources to learn from?\n\nYes! Please see the [Resources](../resources/resources-and-support.md) page.\n\n### Can I save the result of a query for reusability?\n\nYou can write reusable Javascript Queries with the [dv.view](../api/code-reference.md#dvviewpath-input) function. In DQL, beside the possibility of writing your Query inside a Template and using this template (either with the [Core Plugin Templates](https://help.obsidian.md/Plugins/Templates) or the popular Community Plugin [Templater](https://obsidian.md/plugins?id=templater-obsidian)), you can **save calculations in metadata fields via [Inline DQL](../queries/dql-js-inline.md#inline-dql)**, for example:\n\n```markdown\nstart:: 07h00m\nend:: 18h00m\npause:: 01h30m\nduration:: `= this.end - this.start - this.pause`\n```\n\nYou can list the value (9h 30m in our example) then i.e. in a TABLE without needing to repeat the calculation:\n\n~~~markdown\n```dataview\nTABLE start, end, duration\nWHERE duration\n```\n~~~\n\nGives you\n\n| File (1)\t| start| \tend| \tduration|\n| ---- | ----- | ------ | ----- |\n| Example | 7 hours\t| 18 hours| \t9 hours, 30 minutes |\n\n**But storing a Inline DQL in a field comes with a limitation**: While the value that gets displayed in the result is the calculated one, **the saved value inside your metadata field is still your Inline DQL calculation**. The value is literally `= this.end - this.start - this.pause`. This means you cannot filter for the Inlines' result like:\n\n~~~markdown\n```dataview\nTABLE start, end, duration\nWHERE duration > dur(\"10h\")\n```\n~~~\n\nThis will give you back the example page, even though the result doesn't fulfill the `WHERE` clause, because the value you are comparing against is `= this.end - this.start - this.pause` and is not a duration.\n\n### How can I hide the result count on TABLE Queries?\n\nWith Dataview 0.5.52, you can hide the result count on TABLE and TASK Queries via a setting. Go to Dataview's settings -> Display result count.\n\n### How can I style my queries?\n\nYou can use [CSS Snippets](https://help.obsidian.md/Extending+Obsidian/CSS+snippets) to define custom styling in general for Obsidian. So if you define `cssclasses: myTable` as a property, and enable the snippet below you could set the background color of a table from dataview. Similar to target the outer <ul> of a `TASK` or `LIST` query, you could use the `ul.contains-task-list` or `ul.list-view-ul` respectively.\n\n```css\n.myTable dataview.table {\n background-color: green\n}\n```\n\nIn general there are no unique ID's given to a specific table on a page, so the mentioned targeting applies to any note having that `cssclasses` defined and **all** tables on that page. Currently you can't target a specific table using an ordinary query, but if you're using javascript, you can add the class `clsname` directly to your query result by doing:\n\n```js\ndv.container.className += ' clsname'\n```\n\nHowever, there is a trick to target any table within Obsidian using tags like in the example below, and that would apply to any table having that tag tag within it. This would apply to both manually and dataview generated tables. To make the snippet below work add the tag `#myId` _anywhere_ within your table output.\n\n```css\n[href=\"#myId\"] {\n display: none; /* Hides the tag from the table view */\n}\n\ntable:has([href=\"#myId\"]) {\n /* Style your table as you like */\n background-color: #262626;\n & tr:nth-child(even) td:first-child{\n background-color: #3f3f3f;\n }\n}\n```\n\nWhich would end up having a grey background on the entire table, and the first cell in every even row a different variant of grey. **Disclaimer:** We're not style gurus, so this is just an example to show some of the syntax needed for styling different parts of a table.\n\nFurthermore, in [Style dataview table columns](https://s-blu.github.io/obsidian_dataview_example_vault/20%20Dataview%20Queries/Style%20dataview%20table%20columns/) @s-blu describes an alternate trick using `` to style various parts of table cells (and columns).\n"
},
{
"path": "docs/docs/resources/resources-and-support.md",
"content": "# Other Resources\n\nThere is a bit of a learning curve to getting started with Dataview.\nThis page is a collection of resources that will help you get started.\nDataview gets new features and fixes fairly frequently so please account for these resources being slightly out of date.\nFeel free to contribute directly to this list, documentation, or even reach out to the authors of the original sources for updates.\n\n## Resources\n\n### The Obsidian Hub\n\n- SkepticMystic's [Introduction to Dataview](https://publish.obsidian.md/hub/04+-+Guides%2C+Workflows%2C+%26+Courses/Community+Talks/YT+-+An+Introduction+to+Dataview) supplemented by [a textual guide](https://publish.obsidian.md/hub/04+-+Guides%2C+Workflows%2C+%26+Courses/Guides/An+Introduction+to+Dataview)\n\n### YouTube videos\n\n- SkepticMystic's aforementioned community talk\n- [Dataview Plugin: How To Use This Powerful Obsidian Plugin (With Examples) by Filipe Donadio](https://www.youtube.com/watch?v=7kFEl7Ovsr8)\n- [Automate Your Vault With Dataview - How To Use Dataview in Obsidian by FromSergio](https://www.youtube.com/watch?v=8yjNuiSBSAM)\n- [How to use the Obsidian Dataview plugin by Nicole van der Hoeven](https://www.youtube.com/watch?v=JTObSymEvWA)\n- [Intro to Dataview Plugin - Obsidian Community Talk](https://www.youtube.com/watch?v=lclif6l9UgQ)\n\n### Example Vault\n\n- @s-blu has very kindly put together [a vault of example queries](https://github.com/s-blu/obsidian_dataview_example_vault/) that you can use as a playground of sorts.\n\n### Blog Posts\n\n- [Obsidian Dataview For Beginners: A checklist to help fix your dataview queries](https://denisetodd.medium.com/obsidian-dataview-for-beginners-a-checklist-to-help-fix-your-dataview-queries-11acc57f1e48)\n\n### GitHub Discussion\n\nThe GitHub repository has a fairly active [Discussions Page](https://github.com/blacksmithgu/obsidian-dataview/discussions/) with dozens of answered questions.\n\n### Obsidian Forums\n\nThe [Obsidian Forums](https://forum.obsidian.md/) have a wealth of questions and answers and other interesting tidbits as well.\nTry searching the forums for an answer, especially if it seems like a beginner question.\n\n### Discord\n\nThe [Obsidian Members Group Discord server](https://obsidian.md/community) has a `#dataview` channel.\nOnce again, more likely than not, your question has been asked before so try searching the thread though it is known that Discord's search can be spotty.\nIn case you don't find anything satisfactory, \nThis is the closest you'll get to real-time support but there are no guarantees of instant replies.\nThere are many helpful people though so don't be afraid to ask.\n\n## Support\n\nWhere do you go when you have questions?\nHere's what we recommend you try.\n\n1. Search GitHub Discussions and the Obsidian Forums for your question.\n2. Search through Discord for possible solutions.\n3. Depending on the complexity of the your question:\n - If you need close to synchronous communication, use Discord. Note that we are a community of volunteers and there may be delays in responding.\n - If you expect your problem needs time over multiple days and asynchronous communication, open a GitHub discussion.\n4. If you found a bug, please report it in [the repo's issues](https://github.com/blacksmithgu/obsidian-dataview/issues).\n"
},
{
"path": "docs/mkdocs.yml",
"content": "site_name: Dataview\nrepo_url: https://github.com/blacksmithgu/obsidian-dataview\nedit_uri: edit/master/docs/docs/\nmarkdown_extensions:\n - abbr\n - admonition\n - pymdownx.highlight\n - pymdownx.superfences\n - pymdownx.tabbed\n - pymdownx.tasklist\ntheme:\n name: material\n palette:\n primary: deep purple\n logo: assets/obsidian.png\n favicon: assets/obsidian.png\n custom_dir: overrides\nnav:\n - Overview: 'index.md'\n - Metadata:\n - Adding Metadata: 'annotation/add-metadata.md'\n - Data Types: 'annotation/types-of-metadata.md'\n - Metadata on Pages: 'annotation/metadata-pages.md'\n - Metadata on Tasks and Lists: 'annotation/metadata-tasks.md'\n - DQL, JS and Inlines: 'queries/dql-js-inline.md'\n - Query Language Reference:\n - Structure of a Query: 'queries/structure.md'\n - Query Types: 'queries/query-types.md'\n - Data Commands: 'queries/data-commands.md'\n - Differences to SQL: 'queries/differences-to-sql.md'\n - Sources: 'reference/sources.md'\n - Expressions: 'reference/expressions.md'\n - Literals: 'reference/literals.md'\n - Functions: 'reference/functions.md'\n - JavaScript Reference:\n - Overview: 'api/intro.md'\n - Data Arrays: 'api/data-array.md'\n - Codeblock Reference: 'api/code-reference.md'\n - Codeblock Examples: 'api/code-examples.md'\n - FAQ and Resources:\n - Frequently Asked Questions: 'resources/faq.md'\n - Examples: 'resources/examples.md'\n - Developing Against Dataview: 'resources/develop-against-dataview.md'\n - Resources and Support: 'resources/resources-and-support.md'\n - Friends of Dataview: 'friends.md'\n - Changelog: 'changelog.md'\nplugins:\n - search\n - redirects:\n redirect_maps:\n docs/where-data-comes-from.md: annotation/add-metadata.md\n docs/creating-queries.md: queries/dql-js-inline.md\n docs/query/queries.md: queries/structure.md\n docs/query/expressions.md: reference/expressions.md\n docs/query/sources.md: reference/sources.md\n docs/query/functions.md: reference/functions.md\n docs/query/examples.md: resources/examples.md\n docs/api/intro.md: api/intro.md\n docs/api/data-array.md: api/data-array.md\n docs/api/code-reference.md: api/code-reference.md\n docs/api/code-examples.md: api/code-examples.md\n data-queries.md: queries/dql-js-inline.md\n query/queries.md: queries/structure.md\n data-annotation.md: annotation/add-metadata.md\n resources-and-support.md: resources/resources-and-support.md\n plugin/develop-against-dataview.md: resources/develop-against-dataview.md\n reference/faq.md: resources/faq.md\n reference/examples.md: resources/examples.md\n"
},
{
"path": "docs/overrides/main.html",
"content": "{% extends \"base.html\" %}\n"
},
{
"path": "jest.config.js",
"content": "module.exports = {\n preset: \"ts-jest\",\n testEnvironment: \"jsdom\",\n moduleDirectories: [\"node_modules\", \"src\"],\n};\n"
},
{
"path": "manifest-beta.json",
"content": "{\n \"id\": \"dataview\",\n \"name\": \"Dataview\",\n \"version\": \"0.5.70\",\n \"minAppVersion\": \"0.13.11\",\n \"description\": \"Complex data views for the data-obsessed.\",\n \"author\": \"Michael Brenan \",\n \"authorUrl\": \"https://github.com/blacksmithgu\",\n \"helpUrl\": \"https://blacksmithgu.github.io/obsidian-dataview/\",\n \"isDesktopOnly\": false\n}\n"
},
{
"path": "manifest.json",
"content": "{\n \"id\": \"dataview\",\n \"name\": \"Dataview\",\n \"version\": \"0.5.68\",\n \"minAppVersion\": \"0.13.11\",\n \"description\": \"Complex data views for the data-obsessed.\",\n \"author\": \"Michael Brenan \",\n \"authorUrl\": \"https://github.com/blacksmithgu\",\n \"helpUrl\": \"https://blacksmithgu.github.io/obsidian-dataview/\",\n \"isDesktopOnly\": false\n}\n"
},
{
"path": "package.json",
"content": "{\n \"name\": \"obsidian-dataview\",\n \"version\": \"0.5.70\",\n \"description\": \"Advanced data views for Obsidian.md.\",\n \"main\": \"lib/index.js\",\n \"types\": \"lib/index.d.ts\",\n \"files\": [\n \"lib/**/*\"\n ],\n \"scripts\": {\n \"bdd\": \"npx jest -i --watch --no-cache\",\n \"build\": \"npx rollup --config rollup.config.js --environment BUILD:production\",\n \"check-format\": \"npx prettier --check src\",\n \"dev\": \"npx rollup --config rollup.config.js -w\",\n \"format\": \"npx prettier --write src\",\n \"lib\": \"npx rollup --config rollup.config.js --environment BUILD:lib\",\n \"test\": \"npx jest\"\n },\n \"keywords\": [\n \"obsidian\",\n \"dataview\"\n ],\n \"author\": \"Michael Brenan\",\n \"license\": \"MIT\",\n \"devDependencies\": {\n \"@rollup/plugin-commonjs\": \"^25.0.4\",\n \"@rollup/plugin-node-resolve\": \"^15.2.1\",\n \"@rollup/plugin-typescript\": \"^11.1.3\",\n \"@types/jest\": \"^27.0.1\",\n \"@types/luxon\": \"^3.2.0\",\n \"@types/node\": \"^16.7.13\",\n \"@types/papaparse\": \"^5.2.6\",\n \"@types/parsimmon\": \"^1.10.6\",\n \"@zerollup/ts-transform-paths\": \"^1.7.18\",\n \"compare-versions\": \"^4.1.1\",\n \"jest\": \"^29.7.0\",\n \"jest-environment-jsdom\": \"^29.7.0\",\n \"obsidian\": \"^1.4.0\",\n \"prettier\": \"2.3.2\",\n \"rollup\": \"^2.79.1\",\n \"rollup-jest\": \"^3.1.0\",\n \"rollup-plugin-copy\": \"^3.5.0\",\n \"rollup-plugin-typescript2\": \"^0.35.0\",\n \"rollup-plugin-web-worker-loader\": \"^1.6.1\",\n \"ts-jest\": \"^29.1.1\",\n \"tslib\": \"^2.6.2\",\n \"typescript\": \"^5.2.2\"\n },\n \"dependencies\": {\n \"@codemirror/language\": \"https://github.com/lishid/cm-language\",\n \"@codemirror/state\": \"^6.0.1\",\n \"@codemirror/view\": \"^6.0.1\",\n \"emoji-regex\": \"^10.0.0\",\n \"localforage\": \"^1.10.0\",\n \"luxon\": \"^3.2.0\",\n \"obsidian-calendar-ui\": \"^0.3.12\",\n \"papaparse\": \"^5.3.1\",\n \"parsimmon\": \"^1.18.0\",\n \"preact\": \"^10.6.5\",\n \"remove-markdown\": \"^0.5.5\"\n }\n}\n"
},
{
"path": "rollup.config.js",
"content": "import nodeResolve from \"@rollup/plugin-node-resolve\";\nimport commonjs from \"@rollup/plugin-commonjs\";\nimport webWorker from \"rollup-plugin-web-worker-loader\";\nimport copy from \"rollup-plugin-copy\";\nimport typescript2 from \"rollup-plugin-typescript2\";\n\nconst BASE_CONFIG = {\n input: \"src/main.ts\",\n external: [\"obsidian\", \"@codemirror/view\", \"@codemirror/state\", \"@codemirror/language\"],\n onwarn: (warning, warn) => {\n // Sorry rollup, but we're using eval...\n if (/Use of eval is strongly discouraged/.test(warning.message)) return;\n warn(warning);\n },\n};\n\nconst getRollupPlugins = (tsconfig, ...plugins) =>\n [\n typescript2(tsconfig),\n nodeResolve({ browser: true }),\n commonjs(),\n webWorker({ inline: true, forceInline: true, targetPlatform: \"browser\" }),\n ].concat(plugins);\n\nconst DEV_PLUGIN_CONFIG = {\n ...BASE_CONFIG,\n output: {\n dir: \"test-vault/.obsidian/plugins/dataview\",\n sourcemap: \"inline\",\n format: \"cjs\",\n exports: \"default\",\n name: \"Dataview (Development)\",\n },\n plugins: getRollupPlugins(\n undefined,\n copy({\n targets: [\n { src: \"manifest.json\", dest: \"test-vault/.obsidian/plugins/dataview/\" },\n { src: \"styles.css\", dest: \"test-vault/.obsidian/plugins/dataview/\" },\n ],\n })\n ),\n};\n\nconst PROD_PLUGIN_CONFIG = {\n ...BASE_CONFIG,\n output: {\n dir: \"build\",\n sourcemap: \"inline\",\n sourcemapExcludeSources: true,\n format: \"cjs\",\n exports: \"default\",\n name: \"Dataview (Production)\",\n },\n plugins: getRollupPlugins(),\n};\n\nconst LIBRARY_CONFIG = {\n ...BASE_CONFIG,\n input: \"src/index.ts\",\n output: {\n dir: \"lib\",\n sourcemap: true,\n format: \"cjs\",\n name: \"Dataview (Library)\",\n },\n plugins: getRollupPlugins(\n { tsconfig: \"tsconfig-lib.json\" },\n copy({ targets: [{ src: \"src/typings/*.d.ts\", dest: \"lib/typings\" }] })\n ),\n};\n\nlet configs = [];\nif (process.env.BUILD === \"lib\") {\n // Library build, only library code.\n configs.push(LIBRARY_CONFIG);\n} else if (process.env.BUILD === \"production\") {\n // Production build, build library and main plugin.\n configs.push(LIBRARY_CONFIG, PROD_PLUGIN_CONFIG);\n} else if (process.env.BUILD === \"dev\") {\n // Dev build, only build the plugin.\n configs.push(DEV_PLUGIN_CONFIG);\n} else {\n // Default to the dev build.\n configs.push(DEV_PLUGIN_CONFIG);\n}\n\nexport default configs;\n"
},
{
"path": "scripts/beta-release",
"content": "#!/usr/bin/env bash\n# Automatically update versions in files and create an autorelease.\n# Requires the github CLI, and the jq command\n\nEXIT=\"\"\nNEW_VERSION=$1\n\nif [ -z \"$EDITOR\" ]; then\n echo \"Specify which editor to use in EDITOR, or by doing: EDITOR=vi ./scripts/beta-release 0.x.y\"\n EXIT=1\nfi\n\nif ! command -v jq 2>&1 >/dev/null; then\n echo \"This script relies on the 'jq' command, please install it\"\n EXIT=1\nfi\n\nif ! command -v gh 2>&1 >/dev/null; then\n echo \"This script relies on the 'gh' command from the Github CLI package, please install it\"\n EXIT=1\nfi\n\nif [ $EXIT ]; then\n exit $EXIT\nfi\n\nif [ -z \"$NEW_VERSION\" ]; then\n NEW_VERSION=$(jq -r \".version\" manifest-beta.json | awk -F. -v OFS=. '{$NF += 1 ; print}')\nfi\n\nif [ -z \"$NEW_VERSION\" ]; then\n echo \"Auto-generating next version number failed, please specify next version : ./scripts/beta-release 0.x.y\"\n exit 1\nfi\n\necho \"Releasing beta version '${NEW_VERSION}'\"\n\n# Let users edit release-notes.txt for release notes.\nrm -f release-notes.md\ntouch release-notes.md\necho -e \"# ${NEW_VERSION} (Beta)\\n\\n\" >> release-notes.md\n$EDITOR release-notes.md\n\n# Append release notes to CHANGELOG.md.\nmv CHANGELOG.md CHANGELOG-TEMP.md\ncp release-notes.md CHANGELOG.md\necho -e \"\\n---\\n\" >> CHANGELOG.md\ncat CHANGELOG-TEMP.md >> CHANGELOG.md\nrm -f CHANGELOG-TEMP.md\n\n# Overwrite the documentation changelog.\ncp -f CHANGELOG.md docs/docs/changelog.md\n\n# Delete old files if they exist\nrm -f package.tmp.json\nrm -f manifest-beta.tmp.json\nrm -f versions.tmp.json\n\n# Rewrite versions in relevant files.\njq \".version=\\\"${NEW_VERSION}\\\"\" package.json > package.tmp.json && mv package.tmp.json package.json\njq \".version=\\\"${NEW_VERSION}\\\"\" manifest-beta.json > manifest-beta.tmp.json && mv manifest-beta.tmp.json manifest-beta.json\njq \". + {\\\"${NEW_VERSION}\\\": \\\"0.13.11\\\"}\" versions.json > versions.tmp.json && mv versions.tmp.json versions.json\n\n# Create commit & commit.\ngit commit -a -m \"Auto-release beta ${NEW_VERSION}\"\ngit push\n\n# Rebuild the project to prepare for a release.\nnpm run build\n\n# release api\nnpm publish --tag beta --access public\n\n# And do a github release.\ngh release create \"${NEW_VERSION}\" --pre-release build/main.js styles.css manifest.json --title \"${NEW_VERSION}\" --notes-file release-notes.md\nrm -f release-notes.md\n"
},
{
"path": "scripts/install-built",
"content": "#!/usr/bin/env bash\n# Builds dataview and allows you to provide a path to the vault that it should be installed in.\n# Useful for when you want to dry-run the plugin in a vault other than the test vault.\n\nVAULT=\"$1\"\nTARGET=\"$VAULT/.obsidian/plugins/dataview/\"\nmkdir -p \"$TARGET\"\ncp -f build/main.js styles.css \"$TARGET\"\ncp -f manifest-beta.json \"$TARGET/manifest.json\"\necho Installed plugin files to \"$TARGET\"\n"
},
{
"path": "scripts/release",
"content": "#!/usr/bin/env bash\n# Automatically update versions in files and create an autorelease.\n# Requires the github CLI and jq (if you don't update the version manually).\nEXIT=\"\"\nNEW_VERSION=$1\n\nif [ -z \"$EDITOR\" ]; then\n echo \"Specify which editor to use in EDITOR, or by doing: EDITOR=vi ./scripts/release 0.x.y\"\n EXIT=1\nfi\n\nif ! command -v jq 2>&1 >/dev/null; then\n echo \"This script relies on the 'jq' command, please install it\"\n EXIT=1\nfi\n\nif ! command -v gh 2>&1 >/dev/null; then\n echo \"This script relies on the 'gh' command from the Github CLI package, please install it\"\n EXIT=1\nfi\n\nif [ $EXIT ]; then\n exit $EXIT\nfi\n\nif [ -z \"$NEW_VERSION\" ]; then\n NEW_VERSION=$(jq -r \".version\" manifest-beta.json | awk -F. -v OFS=. '{$NF += 1 ; print}')\nfi\n\nif [ -z \"$NEW_VERSION\" ]; then\n echo \"Auto-generating next version number failed, please specify next version : ./scripts/release 0.x.y\"\n exit 1\nfi\n\n# Let users edit release-notes.txt for release notes.\nrm -f release-notes.md\ntouch release-notes.md\necho -e \"# ${NEW_VERSION}\\n\\n\" >> release-notes.md\n$EDITOR release-notes.md\n\n# Append release notes to CHANGELOG.md.\nmv CHANGELOG.md CHANGELOG-TEMP.md\ncp release-notes.md CHANGELOG.md\necho -e \"\\n---\\n\" >> CHANGELOG.md\ncat CHANGELOG-TEMP.md >> CHANGELOG.md\nrm -f CHANGELOG-TEMP.md\n\n# Overwrite the documentation changelog.\ncp -f CHANGELOG.md docs/docs/changelog.md\n\n# Delete old files if they exist\nrm -f package.tmp.json\nrm -f manifest.tmp.json\nrm -f manifest-beta.tmp.json\nrm -f versions.tmp.json\n\n# Rewrite versions in relevant files.\njq \".version=\\\"${NEW_VERSION}\\\"\" package.json > package.tmp.json && mv package.tmp.json package.json\njq \".version=\\\"${NEW_VERSION}\\\"\" manifest.json > manifest.tmp.json && mv manifest.tmp.json manifest.json\njq \".version=\\\"${NEW_VERSION}\\\"\" manifest-beta.json > manifest-beta.tmp.json && mv manifest-beta.tmp.json manifest-beta.json\njq \". + {\\\"${NEW_VERSION}\\\": \\\"0.12.0\\\"}\" versions.json > versions.tmp.json && mv versions.tmp.json versions.json\n\n# Overwrite the beta manifest as well.\ncp manifest.json manifest-beta.json\n\n# Create commit & commit.\ngit commit -a -m \"Auto-release ${NEW_VERSION}\"\ngit push\n\n# Rebuild the project to prepare for a release.\nnpm run build\n\n# release api\nnpm publish --access public\n\n# And do a github release.\ngh release create \"${NEW_VERSION}\" build/main.js styles.css manifest.json --title \"${NEW_VERSION}\" --notes-file release-notes.md\nrm -f release-notes.md\n"
},
{
"path": "src/api/data-array.ts",
"content": "import { Groupings, Values } from \"data-model/value\";\nimport { QuerySettings } from \"settings\";\n\n/** A function which maps an array element to some value. */\nexport type ArrayFunc = (elem: T, index: number, arr: T[]) => O;\n\n/** A function which compares two types. */\nexport type ArrayComparator = (a: T, b: T) => number;\n\n/** Finds the value of the lowest value type in a grouping. */\nexport type LowestKey = T extends { key: any; rows: any } ? LowestKey : T;\n\n/** A ridiculous type which properly types the result of the 'groupIn' command. */\nexport type Ingrouped = T extends { key: any; rows: any }\n ? { key: T[\"key\"]; rows: Ingrouped }\n : { key: U; rows: T[] };\n\n/**\n * Proxied interface which allows manipulating array-based data. All functions on a data array produce a NEW array\n * (i.e., the arrays are immutable).\n */\nexport interface DataArray {\n /** The total number of elements in the array. */\n length: number;\n\n /** Filter the data array down to just elements which match the given predicate. */\n where(predicate: ArrayFunc): DataArray;\n /** Alias for 'where' for people who want array semantics. */\n filter(predicate: ArrayFunc): DataArray;\n\n /** Map elements in the data array by applying a function to each. */\n map(f: ArrayFunc): DataArray;\n /** Map elements in the data array by applying a function to each, then flatten the results to produce a new array. */\n flatMap(f: ArrayFunc): DataArray;\n /** Mutably change each value in the array, returning the same array which you can further chain off of. */\n mutate(f: ArrayFunc): DataArray;\n\n /** Limit the total number of entries in the array to the given value. */\n limit(count: number): DataArray;\n /**\n * Take a slice of the array. If `start` is undefined, it is assumed to be 0; if `end` is undefined, it is assumed\n * to be the end of the array.\n */\n slice(start?: number, end?: number): DataArray;\n /** Concatenate the values in this data array with those of another iterable / data array / array. */\n concat(other: Iterable): DataArray;\n\n /** Return the first index of the given (optionally starting the search) */\n indexOf(element: T, fromIndex?: number): number;\n /** Return the first element that satisfies the given predicate. */\n find(pred: ArrayFunc): T | undefined;\n /** Find the index of the first element that satisfies the given predicate. Returns -1 if nothing was found. */\n findIndex(pred: ArrayFunc, fromIndex?: number): number;\n /** Returns true if the array contains the given element, and false otherwise. */\n includes(element: T): boolean;\n\n /**\n * Return a string obtained by converting each element in the array to a string, and joining it with the\n * given separator (which defaults to ', ').\n */\n join(sep?: string): string;\n\n /**\n * Return a sorted array sorted by the given key; an optional comparator can be provided, which will\n * be used to compare the keys in lieu of the default dataview comparator.\n */\n sort(key: ArrayFunc, direction?: \"asc\" | \"desc\", comparator?: ArrayComparator): DataArray;\n\n /**\n * Mutably modify the current array with an in place sort; this is less flexible than a regular sort in exchange\n * for being a little more performant. Only use this is performance is a serious consideration.\n */\n sortInPlace(key: (v: T) => U, direction?: \"asc\" | \"desc\", comparator?: ArrayComparator): DataArray;\n\n /**\n * Return an array where elements are grouped by the given key; the resulting array will have objects of the form\n * { key: , rows: DataArray }.\n */\n groupBy(key: ArrayFunc, comparator?: ArrayComparator): DataArray<{ key: U; rows: DataArray }>;\n\n /**\n * If the array is not grouped, groups it as `groupBy` does; otherwise, groups the elements inside each current\n * group. This allows for top-down recursive grouping which may be easier than bottom-up grouping.\n */\n groupIn(key: ArrayFunc, U>, comparator?: ArrayComparator): DataArray>;\n\n /**\n * Return distinct entries. If a key is provided, then rows with distinct keys are returned.\n */\n distinct(key?: ArrayFunc, comparator?: ArrayComparator): DataArray;\n\n /** Return true if the predicate is true for all values. */\n every(f: ArrayFunc): boolean;\n /** Return true if the predicate is true for at least one value. */\n some(f: ArrayFunc): boolean;\n /** Return true if the predicate is FALSE for all values. */\n none(f: ArrayFunc): boolean;\n\n /** Return the first element in the data array. Returns undefined if the array is empty. */\n first(): T;\n /** Return the last element in the data array. Returns undefined if the array is empty. */\n last(): T;\n\n /** Map every element in this data array to the given key, and then flatten it.*/\n to(key: string): DataArray;\n /** Map every element in this data array to the given key; unlike to(), does not flatten the result. */\n into(key: string): DataArray;\n\n /**\n * Recursively expand the given key, flattening a tree structure based on the key into a flat array. Useful for handling\n * hierarchical data like tasks with 'subtasks'.\n */\n expand(key: string): DataArray;\n\n /** Run a lambda on each element in the array. */\n forEach(f: ArrayFunc): void;\n\n /** Calculate the sum of the elements in the array. */\n sum(): number;\n\n /** Calculate the average of the elements in the array. */\n avg(): number;\n\n /** Calculate the minimum of the elements in the array. */\n min(): number;\n\n /** Calculate the maximum of the elements in the array. */\n max(): number;\n\n /** Convert this to a plain javascript array. */\n array(): T[];\n\n /** Allow iterating directly over the array. */\n [Symbol.iterator](): Iterator;\n\n /** Map indexes to values. */\n [index: number]: any;\n /** Automatic flattening of fields. Equivalent to implicitly calling `array.to(\"field\")` */\n [field: string]: any;\n}\n\n/** Implementation of DataArray, minus the dynamic variable access, which is implemented via proxy. */\nclass DataArrayImpl implements DataArray {\n private static ARRAY_FUNCTIONS: Set = new Set([\n \"where\",\n \"filter\",\n \"map\",\n \"flatMap\",\n \"mutate\",\n \"slice\",\n \"concat\",\n \"indexOf\",\n \"limit\",\n \"find\",\n \"findIndex\",\n \"includes\",\n \"join\",\n \"sort\",\n \"sortInPlace\",\n \"groupBy\",\n \"groupIn\",\n \"distinct\",\n \"every\",\n \"some\",\n \"none\",\n \"first\",\n \"last\",\n \"to\",\n \"into\",\n \"lwrap\",\n \"expand\",\n \"forEach\",\n \"length\",\n \"values\",\n \"array\",\n \"defaultComparator\",\n \"toString\",\n \"settings\",\n \"sum\",\n \"avg\",\n \"min\",\n \"max\",\n ]);\n\n private static ARRAY_PROXY: ProxyHandler> = {\n get: function (target, prop, receiver) {\n if (typeof prop === \"symbol\") return (target as any)[prop];\n else if (typeof prop === \"number\") return target.values[prop];\n else if (prop === \"constructor\") return target.values.constructor;\n else if (!isNaN(parseInt(prop))) return target.values[parseInt(prop)];\n else if (DataArrayImpl.ARRAY_FUNCTIONS.has(prop.toString())) return target[prop.toString()];\n\n return target.to(prop);\n },\n };\n\n public static wrap(\n arr: T[],\n settings: QuerySettings,\n defaultComparator: ArrayComparator = Values.compareValue\n ): DataArray {\n return new Proxy>(\n new DataArrayImpl(arr, settings, defaultComparator),\n DataArrayImpl.ARRAY_PROXY\n );\n }\n\n public length: number;\n [key: string]: any;\n\n private constructor(\n public values: any[],\n public settings: QuerySettings,\n public defaultComparator: ArrayComparator = Values.compareValue\n ) {\n this.length = values.length;\n }\n\n private lwrap(values: U[]): DataArray {\n return DataArrayImpl.wrap(values, this.settings, this.defaultComparator);\n }\n\n public where(predicate: ArrayFunc): DataArray {\n return this.lwrap(this.values.filter(predicate));\n }\n\n public filter(predicate: ArrayFunc): DataArray {\n return this.where(predicate);\n }\n\n public map(f: ArrayFunc): DataArray {\n return this.lwrap(this.values.map(f));\n }\n\n public flatMap(f: ArrayFunc): DataArray {\n let result = [];\n for (let index = 0; index < this.length; index++) {\n let value = f(this.values[index], index, this.values);\n if (!value || value.length == 0) continue;\n\n for (let r of value) result.push(r);\n }\n\n return this.lwrap(result);\n }\n\n public mutate(f: ArrayFunc): DataArray {\n for (let index = 0; index < this.values.length; index++) {\n f(this.values[index], index, this.values);\n }\n\n return this as any;\n }\n\n public limit(count: number): DataArray {\n return this.lwrap(this.values.slice(0, count));\n }\n\n public slice(start?: number, end?: number): DataArray {\n return this.lwrap(this.values.slice(start, end));\n }\n\n public concat(other: DataArray): DataArray {\n return this.lwrap(this.values.concat(other.values));\n }\n\n /** Return the first index of the given (optionally starting the search) */\n public indexOf(element: T, fromIndex?: number): number {\n return this.findIndex(e => this.defaultComparator(e, element) == 0, fromIndex);\n }\n\n /** Return the first element that satisfies the given predicate. */\n public find(pred: ArrayFunc): T | undefined {\n let index = this.findIndex(pred);\n if (index == -1) return undefined;\n else return this.values[index];\n }\n\n public findIndex(pred: ArrayFunc, fromIndex?: number): number {\n for (let index = fromIndex ?? 0; index < this.length; index++) {\n if (pred(this.values[index], index, this.values)) return index;\n }\n\n return -1;\n }\n\n public includes(element: T): boolean {\n return this.indexOf(element, 0) != -1;\n }\n\n public join(sep?: string): string {\n return this.map(s => Values.toString(s, this.settings))\n .array()\n .join(sep ?? \", \");\n }\n\n public sort(key?: ArrayFunc, direction?: \"asc\" | \"desc\", comparator?: ArrayComparator): DataArray {\n if (this.values.length == 0) return this;\n let realComparator = comparator ?? this.defaultComparator;\n let realKey = key ?? ((l: T) => l as any as U);\n\n // Associate each entry with it's index for the key function, and then do a normal sort.\n let copy = ([] as any[]).concat(this.array()).map((elem, index) => {\n return { index: index, value: elem };\n });\n copy.sort((a, b) => {\n let aKey = realKey(a.value, a.index, this.values);\n let bKey = realKey(b.value, b.index, this.values);\n return direction === \"desc\" ? -realComparator(aKey, bKey) : realComparator(aKey, bKey);\n });\n\n return this.lwrap(copy.map(e => e.value));\n }\n\n public sortInPlace(\n key?: (value: T) => U,\n direction?: \"asc\" | \"desc\",\n comparator?: ArrayComparator\n ): DataArray {\n if (this.values.length == 0) return this;\n let realComparator = comparator ?? this.defaultComparator;\n let realKey = key ?? ((l: T) => l as any as U);\n\n this.values.sort((a, b) => {\n let aKey = realKey(a);\n let bKey = realKey(b);\n\n return direction == \"desc\" ? -realComparator(aKey, bKey) : realComparator(aKey, bKey);\n });\n\n return this;\n }\n\n public groupBy(\n key: ArrayFunc,\n comparator?: ArrayComparator\n ): DataArray<{ key: U; rows: DataArray }> {\n if (this.values.length == 0) return this.lwrap([]);\n\n // JavaScript sucks and we can't make hash maps over arbitrary types (only strings/ints), so\n // we do a poor man algorithm where we SORT, followed by grouping.\n let intermediate = this.sort(key, \"asc\", comparator);\n comparator = comparator ?? this.defaultComparator;\n\n let result: { key: U; rows: DataArray }[] = [];\n let currentRow = [intermediate[0]];\n let current = key(intermediate[0], 0, intermediate.values);\n for (let index = 1; index < intermediate.length; index++) {\n let newKey = key(intermediate[index], index, intermediate.values);\n if (comparator(current, newKey) != 0) {\n result.push({ key: current, rows: this.lwrap(currentRow) });\n current = newKey;\n currentRow = [intermediate[index]];\n } else {\n currentRow.push(intermediate[index]);\n }\n }\n result.push({ key: current, rows: this.lwrap(currentRow) });\n\n return this.lwrap(result);\n }\n\n public groupIn(key: ArrayFunc, U>, comparator?: ArrayComparator): DataArray> {\n if (Groupings.isGrouping(this.values)) {\n return this.map(v => {\n return {\n key: (v as any).key,\n rows: DataArray.wrap((v as any).rows, this.settings).groupIn(key as any, comparator as any),\n } as any;\n });\n } else {\n return this.groupBy(key as any, comparator) as any;\n }\n }\n\n public distinct(key?: ArrayFunc, comparator?: ArrayComparator): DataArray {\n if (this.values.length == 0) return this;\n let realKey = key ?? (x => x as any as U);\n\n // For similar reasons to groupBy, do a sort and take the first element of each block.\n let intermediate = this.map((x, index) => {\n return { key: realKey(x, index, this.values), value: x };\n }).sort(x => x.key, \"asc\", comparator);\n comparator = comparator ?? this.defaultComparator;\n\n let result: T[] = [intermediate[0].value];\n for (let index = 1; index < intermediate.length; index++) {\n if (comparator(intermediate[index - 1].key, intermediate[index].key) != 0) {\n result.push(intermediate[index].value);\n }\n }\n\n return this.lwrap(result);\n }\n\n public every(f: ArrayFunc): boolean {\n return this.values.every(f);\n }\n\n public some(f: ArrayFunc): boolean {\n return this.values.some(f);\n }\n\n public none(f: ArrayFunc): boolean {\n return this.values.every((v, i, a) => !f(v, i, a));\n }\n\n public first(): T {\n return this.values.length > 0 ? this.values[0] : undefined;\n }\n public last(): T {\n return this.values.length > 0 ? this.values[this.values.length - 1] : undefined;\n }\n\n public to(key: string): DataArray {\n let result: any[] = [];\n for (let child of this.values) {\n let value = child[key];\n if (value === undefined || value === null) continue;\n\n if (Array.isArray(value) || DataArray.isDataArray(value)) value.forEach(v => result.push(v));\n else result.push(value);\n }\n\n return this.lwrap(result);\n }\n\n public into(key: string): DataArray {\n let result: any[] = [];\n for (let child of this.values) {\n let value = child[key];\n if (value === undefined || value === null) continue;\n\n result.push(value);\n }\n\n return this.lwrap(result);\n }\n\n public expand(key: string): DataArray {\n let result = [];\n let queue: any[] = ([] as any[]).concat(this.values);\n\n while (queue.length > 0) {\n let next = queue.pop();\n let value = next[key];\n\n if (value === undefined || value === null) continue;\n if (Array.isArray(value)) value.forEach(v => queue.push(v));\n else if (value instanceof DataArrayImpl) value.forEach(v => queue.push(v));\n else queue.push(value);\n\n result.push(next);\n }\n\n return this.lwrap(result);\n }\n\n public forEach(f: ArrayFunc) {\n for (let index = 0; index < this.values.length; index++) {\n f(this.values[index], index, this.values);\n }\n }\n\n public sum() {\n return this.values.reduce((a, b) => a + b, 0);\n }\n\n public avg() {\n return this.sum() / this.values.length;\n }\n\n public min() {\n return Math.min(...this.values);\n }\n\n public max() {\n return Math.max(...this.values);\n }\n\n public array(): T[] {\n return ([] as any[]).concat(this.values);\n }\n\n public [Symbol.iterator](): Iterator {\n return this.values[Symbol.iterator]();\n }\n\n public toString(): string {\n return \"[\" + this.values.join(\", \") + \"]\";\n }\n}\n\n/** Provides utility functions for generating data arrays. */\nexport namespace DataArray {\n /** Create a new Dataview data array. */\n export function wrap(raw: T[] | DataArray, settings: QuerySettings): DataArray {\n if (isDataArray(raw)) return raw;\n return DataArrayImpl.wrap(raw, settings);\n }\n\n /** Create a new DataArray from an iterable object. */\n export function from(raw: Iterable, settings: QuerySettings): DataArray {\n if (isDataArray(raw)) return raw;\n\n let data = [];\n for (let elem of raw) data.push(elem);\n return DataArrayImpl.wrap(data, settings);\n }\n\n /** Return true if the given object is a data array. */\n export function isDataArray(obj: any): obj is DataArray {\n return obj instanceof DataArrayImpl;\n }\n}\n\n// A scary looking polyfill, sure, but it fixes up data array/array interop for us.\nconst oldArrayIsArray = Array.isArray;\nArray.isArray = (arg): arg is any[] => {\n return oldArrayIsArray(arg) || DataArray.isDataArray(arg);\n};\n"
},
{
"path": "src/api/extensions.ts",
"content": "import { STask } from \"data-model/serialized/markdown\";\n\n/** A general function for deciding how to check a task given it's current state. */\nexport type TaskStatusSelector = (task: STask) => Promise;\n\n/**\n * A dataview extension; allows for registering new functions, altering views, and altering some more\n * advanced dataview behavior.\n **/\nexport class Extension {\n /** All registered task status selectors for this extension. */\n public taskStatusSelectors: Record;\n\n public constructor(public plugin: string) {\n this.taskStatusSelectors = {};\n }\n\n /** Register a task status selector under the given name. */\n public taskStatusSelector(name: string, selector: TaskStatusSelector): Extension {\n this.taskStatusSelectors[name] = selector;\n return this;\n }\n}\n"
},
{
"path": "src/api/inline-api.ts",
"content": "/** Fancy wrappers for the JavaScript API, used both by external plugins AND by the dataview javascript view. */\n\nimport { App, Component } from \"obsidian\";\nimport { FullIndex } from \"data-index\";\nimport { renderValue, renderErrorPre } from \"ui/render\";\nimport type { DataviewApi, DataviewIOApi, QueryApiSettings, QueryResult } from \"api/plugin-api\";\nimport { DataviewSettings, ExportSettings } from \"settings\";\nimport { DataObject, Grouping, Link, Literal, Values, Widgets } from \"data-model/value\";\nimport { BoundFunctionImpl, DEFAULT_FUNCTIONS, Functions } from \"expression/functions\";\nimport { Context } from \"expression/context\";\nimport { defaultLinkHandler } from \"query/engine\";\nimport { DateTime, Duration } from \"luxon\";\nimport * as Luxon from \"luxon\";\nimport { DataArray } from \"./data-array\";\nimport { SListItem } from \"data-model/serialized/markdown\";\nimport { EXPRESSION } from \"expression/parse\";\nimport { Result } from \"api/result\";\n\n/** Asynchronous API calls related to file / system IO. */\nexport class DataviewInlineIOApi {\n public constructor(public api: DataviewIOApi, public currentFile: string) {}\n\n /** Load the contents of a CSV asynchronously, returning a data array of rows (or undefined if it does not exist). */\n public async csv(path: string, originFile?: string): Promise | undefined> {\n return this.api.csv(path, originFile || this.currentFile);\n }\n\n /** Asynchronously load the contents of any link or path in an Obsidian vault. */\n public async load(path: Link | string, originFile?: string): Promise {\n return this.api.load(path, originFile || this.currentFile);\n }\n\n /** Normalize a link or path relative to an optional origin file. Returns a textual fully-qualified-path. */\n public normalize(path: Link | string, originFile?: string): string {\n return this.api.normalize(path, originFile || this.currentFile);\n }\n}\n\nexport class DataviewInlineApi {\n /**\n * The raw dataview indices, which track file <-> metadata relations. Use these if the intuitive API does not support\n * your use case.\n */\n public index: FullIndex;\n\n /** The component that handles the lifetime of this view. Use it if you are adding custom event handlers/components. */\n public component: Component;\n\n /** The path to the current file this script is running in. */\n public currentFilePath: string;\n\n /**\n * The container which holds the output of this view. You can directly append fields to this, if you wish, though\n * the rendering API is likely to be easier for straight-forward purposes.\n */\n public container: HTMLElement;\n\n /** Directly access the Obsidian app object, such as for reaching out to other plugins. */\n public app: App;\n\n /** The general plugin API which much of this inline API delegates to. */\n public api: DataviewApi;\n\n /** Settings which determine defaults, incl. many rendering options. */\n public settings: DataviewSettings;\n\n /** Evaluation context which expressions can be evaluated in. */\n public evaluationContext: Context;\n\n /** Value utilities which allow for type-checking and comparisons. */\n public value = Values;\n\n /** Widget utility functions for creating built-in widgets. */\n public widget = Widgets;\n\n /** IO utilities which are largely asynchronous. */\n public io: DataviewInlineIOApi;\n\n /** Re-exporting of luxon for people who can't easily require it. Sorry! */\n public luxon = Luxon;\n\n /** Dataview functions which can be called from DataviewJS. */\n public func: Record;\n\n constructor(api: DataviewApi, component: Component, container: HTMLElement, currentFilePath: string) {\n this.index = api.index;\n this.app = api.app;\n this.settings = api.settings;\n\n this.component = component;\n this.container = container;\n this.currentFilePath = currentFilePath;\n\n this.api = api;\n this.io = new DataviewInlineIOApi(this.api.io, this.currentFilePath);\n\n // Set up the evaluation context with variables from the current file.\n let fileMeta = this.index.pages.get(this.currentFilePath)?.serialize(this.index) ?? {};\n this.evaluationContext = new Context(defaultLinkHandler(this.index, this.currentFilePath), this.settings, {\n this: fileMeta,\n });\n\n this.func = Functions.bindAll(DEFAULT_FUNCTIONS, this.evaluationContext);\n }\n\n /////////////////////////////\n // Index + Data Collection //\n /////////////////////////////\n\n /** Return an array of paths (as strings) corresponding to pages which match the query. */\n public pagePaths(query?: string): DataArray {\n return this.api.pagePaths(query, this.currentFilePath);\n }\n\n /** Map a page path to the actual data contained within that page. */\n public page(path: string | Link): DataObject | undefined {\n return this.api.page(path, this.currentFilePath);\n }\n\n /** Return an array of page objects corresponding to pages which match the query. */\n public pages(query?: string): DataArray {\n return this.api.pages(query, this.currentFilePath);\n }\n\n /** Return the information about the current page. */\n public current(): Record | undefined {\n return this.page(this.currentFilePath);\n }\n\n ///////////////////////////////\n // Dataview Query Evaluation //\n ///////////////////////////////\n\n /** Execute a Dataview query, returning the results in programmatic form. */\n public async query(\n source: string,\n originFile?: string,\n settings?: QueryApiSettings\n ): Promise> {\n return this.api.query(source, originFile ?? this.currentFilePath, settings);\n }\n\n /** Error-throwing version of {@link query}. */\n public async tryQuery(source: string, originFile?: string, settings?: QueryApiSettings): Promise {\n return this.api.tryQuery(source, originFile ?? this.currentFilePath, settings);\n }\n\n /** Execute a Dataview query, returning the results in Markdown. */\n public async queryMarkdown(\n source: string,\n originFile?: string,\n settings?: QueryApiSettings\n ): Promise> {\n return this.api.queryMarkdown(source, originFile ?? this.currentFilePath, settings);\n }\n\n /** Error-throwing version of {@link queryMarkdown}. */\n public async tryQueryMarkdown(source: string, originFile?: string, settings?: QueryApiSettings): Promise {\n return this.api.tryQueryMarkdown(source, originFile ?? this.currentFilePath, settings);\n }\n\n /**\n * Evaluate a dataview expression (like '2 + 2' or 'link(\"hello\")'), returning the evaluated result.\n * This takes an optional second argument which provides definitions for variables, such as:\n *\n * ```\n * dv.evaluate(\"x + 6\", { x: 2 }) = 8\n * dv.evaluate('link(target)', { target: \"Okay\" }) = [[Okay]]\n * ```\n *\n * Note that `this` is implicitly available and refers to the current file.\n *\n * This method returns a Result type instead of throwing an error; you can check the result of the\n * execution via `result.successful` and obtain `result.value` or `result.error` accordingly. If\n * you'd rather this method throw on an error, use `dv.tryEvaluate`.\n */\n public evaluate(expression: string, context?: DataObject): Result {\n let field = EXPRESSION.field.parse(expression);\n if (!field.status) return Result.failure(`Failed to parse expression \"${expression}\"`);\n\n return this.evaluationContext.evaluate(field.value, context);\n }\n\n /** Error-throwing version of `dv.evaluate`. */\n public tryEvaluate(expression: string, context?: DataObject): Literal {\n return this.evaluate(expression, context).orElseThrow();\n }\n\n /** Execute a Dataview query and embed it into the current view. */\n public async execute(source: string) {\n this.api.execute(source, this.container, this.component, this.currentFilePath);\n }\n\n /** Execute a DataviewJS query and embed it into the current view. */\n public async executeJs(code: string) {\n this.api.executeJs(code, this.container, this.component, this.currentFilePath);\n }\n\n /////////////\n // Utility //\n /////////////\n\n /**\n * Convert an input element or array into a Dataview data-array. If the input is already a data array,\n * it is returned unchanged.\n */\n public array(raw: any): DataArray {\n return this.api.array(raw);\n }\n\n /** Return true if the given value is a javascript array OR a dataview data array. */\n public isArray(raw: any): raw is DataArray | Array {\n return this.api.isArray(raw);\n }\n\n /** Return true if the given value is a dataview data array; this returns FALSE for plain JS arrays. */\n public isDataArray(raw: unknown): raw is DataArray {\n return DataArray.isDataArray(raw);\n }\n\n /** Create a dataview file link to the given path. */\n public fileLink(path: string, embed: boolean = false, display?: string): Link {\n return Link.file(path, embed, display);\n }\n\n /** Create a dataview section link to the given path. */\n public sectionLink(path: string, section: string, embed: boolean = false, display?: string): Link {\n return Link.header(path, section, embed, display);\n }\n\n /** Create a dataview block link to the given path. */\n public blockLink(path: string, blockId: string, embed: boolean = false, display?: string): Link {\n return Link.block(path, blockId, embed, display);\n }\n\n /** Attempt to extract a date from a string, link or date. */\n public date(pathlike: string | Link | DateTime): DateTime | null {\n return this.api.date(pathlike);\n }\n\n /** Attempt to extract a duration from a string or duration. */\n public duration(dur: string | Duration): Duration | null {\n return this.api.duration(dur);\n }\n\n /** Parse a raw textual value into a complex Dataview type, if possible. */\n public parse(value: string): Literal {\n return this.api.parse(value);\n }\n\n /** Convert a basic JS type into a Dataview type by parsing dates, links, durations, and so on. */\n public literal(value: any): Literal {\n return this.api.literal(value);\n }\n\n /** Deep clone the given literal, returning a new literal which is independent of the original. */\n public clone(value: Literal): Literal {\n return Values.deepCopy(value);\n }\n\n /**\n * Compare two arbitrary JavaScript values using Dataview's default comparison rules. Returns a negative value if\n * a < b, 0 if a = b, and a positive value if a > b.\n */\n public compare(a: any, b: any): number {\n return Values.compareValue(a, b);\n }\n\n /** Return true if the two given JavaScript values are equal using Dataview's default comparison rules. */\n public equal(a: any, b: any): boolean {\n return this.compare(a, b) == 0;\n }\n\n /////////////////////////\n // Rendering Functions //\n /////////////////////////\n\n /** Render an HTML element, containing arbitrary text. */\n public el(\n el: K,\n text: any,\n { container = this.container, ...options }: DomElementInfo & { container?: HTMLElement } = {}\n ): HTMLElementTagNameMap[K] {\n let wrapped = Values.wrapValue(text);\n\n if (wrapped === null || wrapped === undefined) {\n return container.createEl(el, Object.assign({ text }, options));\n }\n\n let _el = container.createEl(el, options);\n renderValue(this.app, wrapped.value, _el, this.currentFilePath, this.component, this.settings, true);\n return _el;\n }\n\n /** Render an HTML header; the level can be anything from 1 - 6. */\n public header(level: number, text: any, options?: DomElementInfo): HTMLHeadingElement {\n let header = { 1: \"h1\", 2: \"h2\", 3: \"h3\", 4: \"h4\", 5: \"h5\", 6: \"h6\" }[level];\n if (!header) throw Error(`Unrecognized level '${level}' (expected 1, 2, 3, 4, 5, or 6)`);\n\n return this.el(header as keyof HTMLElementTagNameMap, text, options) as HTMLHeadingElement;\n }\n\n /** Render an HTML paragraph, containing arbitrary text. */\n public paragraph(text: any, options?: DomElementInfo): HTMLParagraphElement {\n return this.el(\"p\", text, options);\n }\n\n /** Render an inline span, containing arbitrary text. */\n public span(text: any, options?: DomElementInfo): HTMLSpanElement {\n return this.el(\"span\", text, options);\n }\n\n /**\n * Render HTML from the output of a template \"view\" saved as a file in the vault.\n * Takes a filename and arbitrary input data.\n */\n public async view(viewName: string, input: any) {\n // Look for `${viewName}.js` first, then for `${viewName}/view.js`.\n const simpleViewPath = `${viewName}.js`;\n const complexViewPath = `${viewName}/view.js`;\n let checkForCss = false;\n let cssElement = undefined;\n let viewFile = this.app.metadataCache.getFirstLinkpathDest(simpleViewPath, this.currentFilePath);\n if (!viewFile) {\n viewFile = this.app.metadataCache.getFirstLinkpathDest(complexViewPath, this.currentFilePath);\n checkForCss = true;\n }\n\n if (!viewFile) {\n renderErrorPre(\n this.container,\n `Dataview: custom view not found for '${simpleViewPath}' or '${complexViewPath}'.`\n );\n return;\n }\n\n if (checkForCss) {\n // Check for optional CSS.\n let cssFile = this.app.metadataCache.getFirstLinkpathDest(`${viewName}/view.css`, this.currentFilePath);\n if (cssFile) {\n let cssContents = await this.app.vault.read(cssFile);\n cssContents += `\\n/*# sourceURL=${location.origin}/${cssFile.path} */`;\n cssElement = this.container.createEl(\"style\", { text: cssContents, attr: { scope: \" \" } });\n }\n }\n\n let contents = await this.app.vault.read(viewFile);\n if (contents.contains(\"await\")) contents = \"(async () => { \" + contents + \" })()\";\n contents += `\\n//# sourceURL=${viewFile.path}`;\n let func = new Function(\"dv\", \"input\", contents);\n\n try {\n // This may directly render, in which case it will likely return undefined or null.\n let result = await Promise.resolve(func(this, input));\n if (result)\n await renderValue(\n this.app,\n result as any,\n this.container,\n this.currentFilePath,\n this.component,\n this.settings,\n true\n );\n } catch (ex) {\n if (cssElement) this.container.removeChild(cssElement);\n renderErrorPre(this.container, `Dataview: Failed to execute view '${viewFile.path}'.\\n\\n${ex}`);\n }\n }\n\n /** Render a dataview list of the given values. */\n public list(values?: any[] | DataArray) {\n return this.api.list(values, this.container, this.component, this.currentFilePath);\n }\n\n /** Render a dataview table with the given headers, and the 2D array of values. */\n public table(headers: string[], values?: any[][] | DataArray) {\n return this.api.table(headers, values, this.container, this.component, this.currentFilePath);\n }\n\n /** Render a dataview task view with the given tasks. */\n public taskList(tasks: Grouping, groupByFile: boolean = true) {\n return this.api.taskList(tasks, groupByFile, this.container, this.component, this.currentFilePath);\n }\n\n ////////////////////////\n // Markdown Rendering //\n ////////////////////////\n\n /** Render a table directly to markdown, returning the markdown. */\n public markdownTable(\n headers: string[],\n values?: any[][] | DataArray,\n settings?: Partial\n ): string {\n return this.api.markdownTable(headers, values, settings);\n }\n\n /** Render a list directly to markdown, returning the markdown. */\n public markdownList(values?: any[] | DataArray | undefined, settings?: Partial) {\n return this.api.markdownList(values, settings);\n }\n\n /** Render at ask list directly to markdown, returning the markdown. */\n public markdownTaskList(values: Grouping, settings?: Partial) {\n return this.api.markdownTaskList(values, settings);\n }\n}\n\n/**\n * Evaluate a script where 'this' for the script is set to the given context. Allows you to define global variables.\n */\nexport function evalInContext(script: string, context: any): any {\n return function () {\n return eval(script);\n }.call(context);\n}\n\n/**\n * Evaluate a script possibly asynchronously, if the script contains `async/await` blocks.\n */\nexport async function asyncEvalInContext(script: string, context: any): Promise {\n if (script.includes(\"await\")) {\n return evalInContext(\"(async () => { \" + script + \" })()\", context) as Promise;\n } else {\n return Promise.resolve(evalInContext(script, context));\n }\n}\n"
},
{
"path": "src/api/plugin-api.ts",
"content": "/** The general, externally accessible plugin API (available at `app.plugins.plugins.dataview.api` or as global `DataviewAPI`). */\n\nimport { App, Component, MarkdownPostProcessorContext, TFile } from \"obsidian\";\nimport { FullIndex } from \"data-index/index\";\nimport { matchingSourcePaths } from \"data-index/resolver\";\nimport { Sources } from \"data-index/source\";\nimport { DataObject, Grouping, Groupings, Link, Literal, Values, Widgets } from \"data-model/value\";\nimport { EXPRESSION } from \"expression/parse\";\nimport { renderCodeBlock, renderErrorPre, renderValue } from \"ui/render\";\nimport { DataArray } from \"./data-array\";\nimport { BoundFunctionImpl, DEFAULT_FUNCTIONS, Functions } from \"expression/functions\";\nimport { Context } from \"expression/context\";\nimport {\n defaultLinkHandler,\n executeCalendar,\n executeInline,\n executeList,\n executeTable,\n executeTask,\n IdentifierMeaning,\n} from \"query/engine\";\nimport { DateTime, Duration } from \"luxon\";\nimport * as Luxon from \"luxon\";\nimport { compare, CompareOperator, satisfies } from \"compare-versions\";\nimport { DataviewSettings, ExportSettings } from \"settings\";\nimport { parseFrontmatter } from \"data-import/markdown-file\";\nimport { SListItem, SMarkdownPage } from \"data-model/serialized/markdown\";\nimport { createFixedTaskView, createTaskView, nestGroups } from \"ui/views/task-view\";\nimport { createFixedListView, createListView } from \"ui/views/list-view\";\nimport { createFixedTableView, createTableView } from \"ui/views/table-view\";\nimport { Result } from \"api/result\";\nimport { parseQuery } from \"query/parse\";\nimport { tryOrPropagate } from \"util/normalize\";\nimport { Query } from \"query/query\";\nimport { DataviewCalendarRenderer } from \"ui/views/calendar-view\";\nimport { DataviewJSRenderer } from \"ui/views/js-view\";\nimport { markdownList, markdownTable, markdownTaskList } from \"ui/export/markdown\";\n\n/** Asynchronous API calls related to file / system IO. */\nexport class DataviewIOApi {\n public constructor(public api: DataviewApi) {}\n\n /** Load the contents of a CSV asynchronously, returning a data array of rows (or undefined if it does not exist). */\n public async csv(path: Link | string, originFile?: string): Promise | undefined> {\n if (!Values.isLink(path) && !Values.isString(path)) {\n throw Error(`dv.io.csv only handles string or link paths; was provided type '${typeof path}'.`);\n }\n\n let data = await this.api.index.csv.get(this.normalize(path, originFile));\n if (data.successful) return DataArray.from(data.value, this.api.settings);\n else throw Error(`Could not find CSV for path '${path}' (relative to origin '${originFile ?? \"/\"}')`);\n }\n\n /** Asynchronously load the contents of any link or path in an Obsidian vault. */\n public async load(path: Link | string, originFile?: string): Promise {\n if (!Values.isLink(path) && !Values.isString(path)) {\n throw Error(`dv.io.load only handles string or link paths; was provided type '${typeof path}'.`);\n }\n\n let existingFile = this.api.index.vault.getAbstractFileByPath(this.normalize(path, originFile));\n if (!existingFile || !(existingFile instanceof TFile)) return undefined;\n\n return this.api.index.vault.cachedRead(existingFile);\n }\n\n /** Normalize a link or path relative to an optional origin file. Returns a textual fully-qualified-path. */\n public normalize(path: Link | string, originFile?: string): string {\n let realPath;\n if (Values.isLink(path)) realPath = path.path;\n else realPath = path;\n\n return this.api.index.prefix.resolveRelative(realPath, originFile);\n }\n}\n\n/** Global API for accessing the Dataview API, executing dataview queries, and */\nexport class DataviewApi {\n /** Evaluation context which expressions can be evaluated in. */\n public evaluationContext: Context;\n /** IO API which supports asynchronous loading of data directly. */\n public io: DataviewIOApi;\n /** Dataview functions which can be called from DataviewJS. */\n public func: Record;\n /** Value utility functions for comparisons and type-checking. */\n public value = Values;\n /** Widget utility functions for creating built-in widgets. */\n public widget = Widgets;\n /** Re-exporting of luxon for people who can't easily require it. Sorry! */\n public luxon = Luxon;\n\n public constructor(\n public app: App,\n public index: FullIndex,\n public settings: DataviewSettings,\n private verNum: string\n ) {\n this.evaluationContext = new Context(defaultLinkHandler(index, \"\"), settings);\n this.func = Functions.bindAll(DEFAULT_FUNCTIONS, this.evaluationContext);\n this.io = new DataviewIOApi(this);\n }\n\n /** Utilities to check the current Dataview version and compare it to SemVer version ranges. */\n public version: {\n current: string;\n compare: (op: CompareOperator, ver: string) => boolean;\n satisfies: (range: string) => boolean;\n } = (() => {\n const self = this;\n return {\n get current() {\n return self.verNum;\n },\n compare: (op: CompareOperator, ver: string) => compare(this.verNum, ver, op),\n satisfies: (range: string) => satisfies(this.verNum, range),\n };\n })();\n\n /////////////////////////////\n // Index + Data Collection //\n /////////////////////////////\n\n /** Return an array of paths (as strings) corresponding to pages which match the query. */\n public pagePaths(query?: string, originFile?: string): DataArray {\n let source;\n try {\n if (!query || query.trim() === \"\") source = Sources.folder(\"\");\n else source = EXPRESSION.source.tryParse(query);\n } catch (ex) {\n throw new Error(`Failed to parse query in 'pagePaths': ${ex}`);\n }\n\n return matchingSourcePaths(source, this.index, originFile)\n .map(s => DataArray.from(s, this.settings))\n .orElseThrow();\n }\n\n /** Map a page path to the actual data contained within that page. */\n public page(path: string | Link, originFile?: string): Record | undefined {\n if (!(typeof path === \"string\") && !Values.isLink(path)) {\n throw Error(\"dv.page only handles string and link paths; was provided type '\" + typeof path + \"'\");\n }\n\n let rawPath = path instanceof Link ? path.path : path;\n let normPath = this.app.metadataCache.getFirstLinkpathDest(rawPath, originFile ?? \"\");\n if (!normPath) return undefined;\n\n let pageObject = this.index.pages.get(normPath.path);\n if (!pageObject) return undefined;\n\n return this._addDataArrays(pageObject.serialize(this.index));\n }\n\n /** Return an array of page objects corresponding to pages which match the source query. */\n public pages(query?: string, originFile?: string): DataArray> {\n return this.pagePaths(query, originFile).flatMap(p => {\n let res = this.page(p, originFile);\n return res ? [res] : [];\n });\n }\n\n /** Remaps important metadata to add data arrays. */\n private _addDataArrays(pageObject: SMarkdownPage): SMarkdownPage {\n // Remap the \"file\" metadata entries to be data arrays.\n for (let [key, value] of Object.entries(pageObject.file)) {\n if (Array.isArray(value)) (pageObject.file as any)[key] = DataArray.wrap(value, this.settings);\n }\n\n return pageObject;\n }\n\n /////////////\n // Utility //\n /////////////\n\n /**\n * Convert an input element or array into a Dataview data-array. If the input is already a data array,\n * it is returned unchanged.\n */\n public array(raw: unknown): DataArray {\n if (DataArray.isDataArray(raw)) return raw;\n if (Array.isArray(raw)) return DataArray.wrap(raw, this.settings);\n return DataArray.wrap([raw], this.settings);\n }\n\n /** Return true if the given value is a javascript array OR a dataview data array. */\n public isArray(raw: unknown): raw is DataArray | Array {\n return DataArray.isDataArray(raw) || Array.isArray(raw);\n }\n\n /** Return true if the given value is a dataview data array; this returns FALSE for plain JS arrays. */\n public isDataArray(raw: unknown): raw is DataArray {\n return DataArray.isDataArray(raw);\n }\n\n /** Create a dataview file link to the given path. */\n public fileLink(path: string, embed: boolean = false, display?: string) {\n return Link.file(path, embed, display);\n }\n\n /** Create a dataview section link to the given path. */\n public sectionLink(path: string, section: string, embed: boolean = false, display?: string): Link {\n return Link.header(path, section, embed, display);\n }\n\n /** Create a dataview block link to the given path. */\n public blockLink(path: string, blockId: string, embed: boolean = false, display?: string): Link {\n return Link.block(path, blockId, embed, display);\n }\n\n /** Attempt to extract a date from a string, link or date. */\n public date(pathlike: string | Link | DateTime): DateTime | null {\n return this.func.date(pathlike) as DateTime | null;\n }\n\n /** Attempt to extract a duration from a string or duration. */\n public duration(str: string | Duration): Duration | null {\n return this.func.dur(str) as Duration | null;\n }\n\n /** Parse a raw textual value into a complex Dataview type, if possible. */\n public parse(value: string): Literal {\n let raw = EXPRESSION.inlineField.parse(value);\n if (raw.status) return raw.value;\n else return value;\n }\n\n /** Convert a basic JS type into a Dataview type by parsing dates, links, durations, and so on. */\n public literal(value: any): Literal {\n return parseFrontmatter(value);\n }\n\n /** Deep clone the given literal, returning a new literal which is independent of the original. */\n public clone(value: Literal): Literal {\n return Values.deepCopy(value);\n }\n\n /**\n * Compare two arbitrary JavaScript values using Dataview's default comparison rules. Returns a negative value if\n * a < b, 0 if a = b, and a positive value if a > b.\n */\n public compare(a: any, b: any): number {\n return Values.compareValue(a, b, this.evaluationContext.linkHandler.normalize);\n }\n\n /** Return true if the two given JavaScript values are equal using Dataview's default comparison rules. */\n public equal(a: any, b: any): boolean {\n return this.compare(a, b) == 0;\n }\n\n ///////////////////////////////\n // Dataview Query Evaluation //\n ///////////////////////////////\n\n /**\n * Execute an arbitrary Dataview query, returning a query result which:\n *\n * 1. Indicates the type of query,\n * 2. Includes the raw AST of the parsed query.\n * 3. Includes the output in the form relevant to that query type.\n *\n * List queries will return a list of objects ({ id, value }); table queries return a header array\n * and a 2D array of values; and task arrays return a Grouping type which allows for recursive\n * task nesting.\n */\n public async query(\n source: string | Query,\n originFile?: string,\n settings?: QueryApiSettings\n ): Promise> {\n const query = typeof source === \"string\" ? parseQuery(source) : Result.success(source);\n if (!query.successful) return query.cast();\n\n const header = query.value.header;\n switch (header.type) {\n case \"calendar\":\n const cres = await executeCalendar(query.value, this.index, originFile ?? \"\", this.settings);\n if (!cres.successful) return cres.cast();\n\n return Result.success({ type: \"calendar\", values: cres.value.data });\n case \"task\":\n const tasks = await executeTask(query.value, originFile ?? \"\", this.index, this.settings);\n if (!tasks.successful) return tasks.cast();\n\n return Result.success({ type: \"task\", values: tasks.value.tasks });\n case \"list\":\n if (settings?.forceId !== undefined) header.showId = settings.forceId;\n\n const lres = await executeList(query.value, this.index, originFile ?? \"\", this.settings);\n if (!lres.successful) return lres.cast();\n\n // TODO: WITHOUT ID probably shouldn't exist, or should be moved to the engine itself.\n // For now, until I fix it up in an upcoming refactor, we re-implement the behavior here.\n\n return Result.success({\n type: \"list\",\n values: lres.value.data,\n primaryMeaning: lres.value.primaryMeaning,\n });\n case \"table\":\n if (settings?.forceId !== undefined) header.showId = settings.forceId;\n\n const tres = await executeTable(query.value, this.index, originFile ?? \"\", this.settings);\n if (!tres.successful) return tres.cast();\n\n return Result.success({\n type: \"table\",\n values: tres.value.data,\n headers: tres.value.names,\n idMeaning: tres.value.idMeaning,\n });\n }\n }\n\n /** Error-throwing version of {@link query}. */\n public async tryQuery(source: string, originFile?: string, settings?: QueryApiSettings): Promise {\n return (await this.query(source, originFile, settings)).orElseThrow();\n }\n\n /** Execute an arbitrary dataview query, returning the results in well-formatted markdown. */\n public async queryMarkdown(\n source: string | Query,\n originFile?: string,\n settings?: Partial\n ): Promise> {\n const result = await this.query(source, originFile, settings);\n if (!result.successful) return result.cast();\n\n switch (result.value.type) {\n case \"list\":\n return Result.success(this.markdownList(result.value.values, settings));\n case \"table\":\n return Result.success(this.markdownTable(result.value.headers, result.value.values, settings));\n case \"task\":\n return Result.success(this.markdownTaskList(result.value.values, settings));\n case \"calendar\":\n return Result.failure(\"Cannot render calendar queries to markdown.\");\n }\n }\n\n /** Error-throwing version of {@link queryMarkdown}. */\n public async tryQueryMarkdown(\n source: string | Query,\n originFile?: string,\n settings?: Partial\n ): Promise {\n return (await this.queryMarkdown(source, originFile, settings)).orElseThrow();\n }\n\n /**\n * Evaluate a dataview expression (like '2 + 2' or 'link(\"hello\")'), returning the evaluated result.\n * This takes an optional second argument which provides definitions for variables, such as:\n *\n * ```\n * dv.evaluate(\"x + 6\", { x: 2 }) = 8\n * dv.evaluate('link(target)', { target: \"Okay\" }) = [[Okay]]\n * ```\n *\n * This method returns a Result type instead of throwing an error; you can check the result of the\n * execution via `result.successful` and obtain `result.value` or `result.error` accordingly. If\n * you'd rather this method throw on an error, use `dv.tryEvaluate`.\n */\n public evaluate(expression: string, context?: DataObject, originFile?: string): Result {\n let field = EXPRESSION.field.parse(expression);\n if (!field.status) return Result.failure(`Failed to parse expression \"${expression}\"`);\n\n let evaluationContext = originFile\n ? new Context(defaultLinkHandler(this.index, originFile), this.settings)\n : this.evaluationContext;\n\n return evaluationContext.evaluate(field.value, context);\n }\n\n /** Error-throwing version of `dv.evaluate`. */\n public tryEvaluate(expression: string, context?: DataObject, originFile?: string): Literal {\n return this.evaluate(expression, context, originFile).orElseThrow();\n }\n\n /** Evaluate an expression in the context of the given file. */\n public evaluateInline(expression: string, origin: string): Result {\n let field = EXPRESSION.field.parse(expression);\n if (!field.status) return Result.failure(`Failed to parse expression \"${expression}\"`);\n\n return executeInline(field.value, origin, this.index, this.settings);\n }\n\n ///////////////\n // Rendering //\n ///////////////\n\n /**\n * Execute the given query, rendering results into the given container using the components lifecycle.\n * Your component should be a *real* component which calls onload() on it's child components at some point,\n * or a MarkdownPostProcessorContext!\n *\n * Note that views made in this way are live updating and will automatically clean themselves up when\n * the component is unloaded or the container is removed.\n */\n public async execute(\n source: string,\n container: HTMLElement,\n component: Component | MarkdownPostProcessorContext,\n filePath: string\n ) {\n if (isDataviewDisabled(filePath)) {\n renderCodeBlock(container, source);\n return;\n }\n\n let maybeQuery = tryOrPropagate(() => parseQuery(source));\n\n // In case of parse error, just render the error.\n if (!maybeQuery.successful) {\n renderErrorPre(container, \"Dataview: \" + maybeQuery.error);\n return;\n }\n\n let query = maybeQuery.value;\n let init = { app: this.app, settings: this.settings, index: this.index, container };\n let childComponent;\n switch (query.header.type) {\n case \"task\":\n childComponent = createTaskView(init, query as Query, filePath);\n component.addChild(childComponent);\n break;\n case \"list\":\n childComponent = createListView(init, query as Query, filePath);\n component.addChild(childComponent);\n\n break;\n case \"table\":\n childComponent = createTableView(init, query as Query, filePath);\n\n component.addChild(childComponent);\n break;\n case \"calendar\":\n childComponent = new DataviewCalendarRenderer(\n query as Query,\n container,\n this.index,\n filePath,\n this.settings,\n this.app\n );\n\n component.addChild(childComponent);\n break;\n }\n childComponent.load();\n }\n\n /**\n * Execute the given DataviewJS query, rendering results into the given container using the components lifecycle.\n * See {@link execute} for general rendering semantics.\n */\n public async executeJs(\n code: string,\n container: HTMLElement,\n component: Component | MarkdownPostProcessorContext,\n filePath: string\n ) {\n if (isDataviewDisabled(filePath)) {\n renderCodeBlock(container, code, \"javascript\");\n return;\n }\n const renderer = new DataviewJSRenderer(this, code, container, filePath);\n renderer.load();\n component.addChild(renderer);\n }\n\n /** Render a dataview list of the given values. */\n public async list(\n values: any[] | DataArray | undefined,\n container: HTMLElement,\n component: Component,\n filePath: string\n ) {\n if (!values) return;\n if (values !== undefined && values !== null && !Array.isArray(values) && !DataArray.isDataArray(values))\n values = Array.from(values);\n\n // Append a child div, since React will keep re-rendering otherwise.\n let subcontainer = container.createEl(\"div\");\n component.addChild(\n createFixedListView(\n { app: this.app, settings: this.settings, index: this.index, container: subcontainer },\n values as Literal[],\n filePath\n )\n );\n }\n\n /** Render a dataview table with the given headers, and the 2D array of values. */\n public async table(\n headers: string[],\n values: any[][] | DataArray | undefined,\n container: HTMLElement,\n component: Component,\n filePath: string\n ) {\n if (!headers) headers = [];\n if (!values) values = [];\n if (!Array.isArray(headers) && !DataArray.isDataArray(headers)) headers = Array.from(headers);\n\n // Append a child div, since React will keep re-rendering otherwise.\n let subcontainer = container.createEl(\"div\");\n component.addChild(\n createFixedTableView(\n { app: this.app, settings: this.settings, index: this.index, container: subcontainer },\n headers,\n values as Literal[][],\n filePath\n )\n );\n }\n\n /** Render a dataview task view with the given tasks. */\n public async taskList(\n tasks: Grouping,\n groupByFile: boolean = true,\n container: HTMLElement,\n component: Component,\n filePath: string = \"\"\n ) {\n let groupedTasks =\n !Groupings.isGrouping(tasks) && groupByFile ? this.array(tasks).groupBy(t => Link.file(t.path)) : tasks;\n\n // Append a child div, since React will override several task lists otherwise.\n let taskContainer = container.createEl(\"div\");\n component.addChild(\n createFixedTaskView(\n { app: this.app, settings: this.settings, index: this.index, container: taskContainer },\n groupedTasks as Grouping,\n filePath\n )\n );\n }\n\n /** Render an arbitrary value into a container. */\n public async renderValue(\n value: any,\n container: HTMLElement,\n component: Component,\n filePath: string,\n inline: boolean = false\n ) {\n return renderValue(this.app, value as Literal, container, filePath, component, this.settings, inline);\n }\n\n /////////////////\n // Data Export //\n /////////////////\n\n /** Render data to a markdown table. */\n public markdownTable(\n headers: string[] | undefined,\n values: any[][] | DataArray | undefined,\n settings?: Partial\n ): string {\n if (!headers) headers = [];\n if (!values) values = [];\n\n const combined = Object.assign({}, this.settings, settings);\n return markdownTable(headers, values as any[][], combined);\n }\n\n /** Render data to a markdown list. */\n public markdownList(values: any[] | DataArray | undefined, settings?: Partial): string {\n if (!values) values = [];\n\n const combined = Object.assign({}, this.settings, settings);\n return markdownList(values as any[], combined);\n }\n\n /** Render tasks or list items to a markdown task list. */\n public markdownTaskList(values: Grouping, settings?: Partial): string {\n if (!values) values = [];\n\n const sparse = nestGroups(values);\n const combined = Object.assign({}, this.settings, settings);\n return markdownTaskList(sparse as any[], combined);\n }\n}\n\n/** The result of executing a table query. */\nexport type TableResult = { type: \"table\"; headers: string[]; values: Literal[][]; idMeaning: IdentifierMeaning };\n/** The result of executing a list query. */\nexport type ListResult = { type: \"list\"; values: Literal[]; primaryMeaning: IdentifierMeaning };\n/** The result of executing a task query. */\nexport type TaskResult = { type: \"task\"; values: Grouping };\n/** The result of executing a calendar query. */\nexport type CalendarResult = {\n type: \"calendar\";\n values: {\n date: DateTime;\n link: Link;\n value?: Literal[];\n }[];\n};\n\n/** The result of executing a query of some sort. */\nexport type QueryResult = TableResult | ListResult | TaskResult | CalendarResult;\n\n/** Settings when querying the dataview API. */\nexport type QueryApiSettings = {\n /** If present, then this forces queries to include/exclude the implicit id field (such as with `WITHOUT ID`). */\n forceId?: boolean;\n};\n\n/** Determines if source-path has a `?no-dataview` annotation that disables dataview. */\nexport function isDataviewDisabled(sourcePath: string): boolean {\n if (!sourcePath) return false;\n\n let questionLocation = sourcePath.lastIndexOf(\"?\");\n if (questionLocation == -1) return false;\n\n return sourcePath.substring(questionLocation).contains(\"no-dataview\");\n}\n"
},
{
"path": "src/api/result.ts",
"content": "/** Functional return type for error handling. */\nexport class Success {\n public successful: true;\n\n public constructor(public value: T) {\n this.successful = true;\n }\n\n public map(f: (a: T) => U): Result {\n return new Success(f(this.value));\n }\n\n public flatMap(f: (a: T) => Result): Result {\n return f(this.value);\n }\n\n public mapErr(f: (e: E) => U): Result ![\"Buy](\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\")