refactor: captures (#613)

* refactor: captures * refactor: make headline detached from template * feat: subtemplates * refactor: move `empty_lines` to `properties` * feat: remove buffer empty lines * fix: properly place capture without headline * tests: add tests for org captures * fix: template validation * chore: remove old tests
nvim-orgmode · Oct 26, 2023 · 938f9af · 938f9af
1 parent 346b6aa
commit 938f9af
Show file tree

Hide file tree

Showing 7 changed files with 581 additions and 108 deletions.
diff --git a/DOCS.md b/DOCS.md
@@ -412,6 +412,16 @@ Variables:
   * `%^{PROMPT|DEFAULT|COMPLETION...}`: Prompt for input, if completion is provided an :h inputlist will be used
   * `%(EXP)`: Runs the given lua code and inserts the result. NOTE: this will internally pass the content to the lua `load()` function. So the body inside `%()` should be the body of a function that returns a string.
 
+Templates have the following fields:
+  * `description` (`string`) — description of the template that is displayed in the template selection menu
+  * `template` (`string|string[]`) — body of the template that will be used when creating capture
+  * `target` (`string?`) — name of the file to which the capture content will be added. If the target is not specified, the content will be added to the [`org_default_notes_file`](#orgdefaultnotesfile) file
+  * `headline` (`string?`) — title of the headline after which the capture content will be added. If no headline is specified, the content will be appended to the end of the file
+  * `properties` (`table?`):
+    * `empty_lines` (`table|number?`) — if the value is a number, then empty lines are added before and after the content. If the value is a table, then the following fields are expected:
+      * `before` (`integer?`) — add empty lines to the beginning of the content
+      * `after` (`integer?`) — add empty lines to the end of the content
+
 Example:<br />
   ```lua
   { T = {
@@ -423,20 +433,24 @@ Example:<br />
 
 Journal example:<br />
   ```lua
-  { j = {
-    description = 'Journal',
-    template = '\n*** %<%Y-%m-%d> %<%A>\n**** %U\n\n%?',
-    target = '~/sync/org/journal.org'
-  } }
+  {
+    j = {
+      description = 'Journal',
+      template = '\n*** %<%Y-%m-%d> %<%A>\n**** %U\n\n%?',
+      target = '~/sync/org/journal.org'
+    },
+  }
   ```
 
 Journal example with dynamic target, i.e. a separate file per month:<br />
   ```lua
-  { J = {
-    description = 'Journal',
-    template = '\n*** %<%Y-%m-%d> %<%A>\n**** %U\n\n%?',
-    target = '~/sync/org/journal/%<%Y-%m>.org'
-  } }
+  {
+    J = {
+      description = 'Journal',
+      template = '\n*** %<%Y-%m-%d> %<%A>\n**** %U\n\n%?',
+      target = '~/sync/org/journal/%<%Y-%m>.org'
+    },
+  }
   ```
 
 Nested key example:<br />
@@ -456,16 +470,38 @@ Nested key example:<br />
       headline = 'one-time'
     }
   }
+  -- or
+  {
+    e = {
+      description = 'Event',
+      subtemplates = {
+        r = {
+          description = 'recurring',
+          template = '** %?\n %T',
+          target = '~/org/calendar.org',
+          headline = 'recurring'
+        },
+        o = {
+          description = 'one-time',
+          template = '** %?\n %T',
+          target = '~/org/calendar.org',
+          headline = 'one-time'
+        },
+      },
+    },
+  }
   ```
 
 Lua expression example:<br />
   ```lua
-  { j = {
-    description = 'Journal',
-    template = '* %(return vim.fn.getreg "w")',
-    -- get the content of register "w"
-    target = '~/sync/org/journal.org'
-  } }
+  { 
+    j = {
+      description = 'Journal',
+      template = '* %(return vim.fn.getreg "w")',
+      -- get the content of register "w"
+      target = '~/sync/org/journal.org'
+    },
+  }
   ```
 
 #### **org_agenda_min_height**