Feat/alias api (#18)

* Remove underscores from headlines in docs * Tweak to avoid stale node aliases being used in api * Move node and completion modules under api * Refactor several of the alias api helper methods to be general utility functions * Lowercase get_property(ID) in capture * Add alias api to documentation * Update readme with references to ROAM_ORIGIN * Add keybindings for adding and removing alias * Add fix to restore normal mode if we were in normal mode before a selection * Update emacs reference to include add/remove alias * Update select ui with default prompt; add custom prompt for alias selection * Bump required version of orgmode
chipsenkbeil · Apr 13, 2024 · 24b6bee · 24b6bee
1 parent 4cef24d
commit 24b6bee
Show file tree

Hide file tree

Showing 9 changed files with 382 additions and 59 deletions.
diff --git a/DOCS.org b/DOCS.org
@@ -6,7 +6,7 @@
 
 ** Installation
 
-   This plugin depends on [[https://github.com/nvim-orgmode/orgmode][nvim-orgmode/orgmode]] @ [[4874e72ab434c440e955b7bc4d9a2df884370137][commit 4874e72]].
+   This plugin depends on [[https://github.com/nvim-orgmode/orgmode][nvim-orgmode/orgmode]] @ [[https://github.com/nvim-orgmode/orgmode/commit/5875037fa9c7c8e0abf29cd69510150355d248a0][commit 5875037]].
 
 *** lazy.nvim
 
@@ -16,7 +16,7 @@
       dependencies = { 
         { 
           "nvim-orgmode/orgmode", 
-          commit = "4874e72ab434c440e955b7bc4d9a2df884370137",
+          commit = "5875037fa9c7c8e0abf29cd69510150355d248a0",
         },
       },
       config = function()
@@ -35,7 +35,7 @@
       requires = { 
         { 
           "nvim-orgmode/orgmode",
-          commit = "4874e72ab434c440e955b7bc4d9a2df884370137",
+          commit = "5875037fa9c7c8e0abf29cd69510150355d248a0",
         },
       },
       config = function()
@@ -65,6 +65,20 @@
 
    Configuration settings used to specify keybindings.
 
+*** add alias
+
+    Adds an alias to the node under cursor.
+
+    Takes a string representing the keybinding. Defaults to =<Leader>naa=.
+
+    #+begin_src lua
+    require("org-roam"):setup({
+      add_alias = {
+        capture = "<LocalLeader>naa",
+      },
+    })
+    #+end_src
+
 *** capture
 
     Opens a roam capture window.
@@ -158,6 +172,20 @@
       },
     })
     #+end_src
+
+*** remove alias
+
+    Removes an alias from the node under cursor.
+
+    Takes a string representing the keybinding. Defaults to =<Leader>nar=.
+
+    #+begin_src lua
+    require("org-roam"):setup({
+      remove_alias = {
+        capture = "<LocalLeader>nar",
+      },
+    })
+    #+end_src
 
 *** toggle roam buffer
 
@@ -231,7 +259,7 @@
 
     If true, updates database whenever a write occurs. If you have large files,
     it is recommended to disable this option and manually update using the vim
-    command =OrgRoamUpdate=.
+    command =RoamUpdate=.
 
     Takes a boolean. Defaults to =true=.
 
@@ -370,16 +398,18 @@
 
 * Bindings
 
-  | Name                     | Keybinding   | Description                                                             |
-  |--------------------------+--------------+-------------------------------------------------------------------------|
-  | capture                  | =<Leader>nc= | Opens org-roam capture window.                                          |
-  | complete_at_point        | =<Leader>n.= | Completes the node under cursor.                                        |
-  | find_node                | =<Leader>nf= | Finds node and moves to it, creating it if it does not exist.           |
-  | insert_node              | =<Leader>ni= | Inserts node at cursor position, creating it if it does not exist.      |
-  | insert_node_immediate    | =<Leader>nm= | Same as =insert_node=, but skips opening capture buffer.                |
-  | quickfix_backlinks       | =<Leader>nq= | Opens the quickfix menu for backlinks to the current node under cursor. |
-  | toggle_roam_buffer       | =<Leader>nl= | Toggles the org-roam node-view buffer for the node under cursor.        |
-  | toggle_roam_buffer_fixed | =<Leader>nb= | Toggles a fixed org-roam node-view buffer for a selected node.          |
+  | Name                     | Keybinding    | Description                                                             |
+  |--------------------------+---------------+-------------------------------------------------------------------------|
+  | add_alias                | =<Leader>naa= | Adds an alias to the node under cursor.                                 |
+  | capture                  | =<Leader>nc=  | Opens org-roam capture window.                                          |
+  | complete_at_point        | =<Leader>n.=  | Completes the node under cursor.                                        |
+  | find_node                | =<Leader>nf=  | Finds node and moves to it, creating it if it does not exist.           |
+  | insert_node              | =<Leader>ni=  | Inserts node at cursor position, creating it if it does not exist.      |
+  | insert_node_immediate    | =<Leader>nm=  | Same as =insert_node=, but skips opening capture buffer.                |
+  | quickfix_backlinks       | =<Leader>nq=  | Opens the quickfix menu for backlinks to the current node under cursor. |
+  | remove_alias             | =<Leader>nar= | Removes an alias from the node under cursor.                            |
+  | toggle_roam_buffer       | =<Leader>nl=  | Toggles the org-roam node-view buffer for the node under cursor.        |
+  | toggle_roam_buffer_fixed | =<Leader>nb=  | Toggles a fixed org-roam node-view buffer for a selected node.          |
 
 ** Modifying bindings
 
@@ -411,12 +441,14 @@
    #+begin_src lua
    require("org-roam"):setup({
      bindings = {
+       add_alias                = "<C-c>naa",
        capture                  = "<C-c>nc",
        complete_at_point        = "<M-/>",
        find_node                = "<C-c>nf",
        insert_node              = "<C-c>ni",
        insert_node_immediate    = "<C-c>nm",
        quickfix_backlinks       = "<C-c>nq",
+       remove_alias             = "<C-c>nar",
        toggle_roam_buffer       = "<C-c>nl",
        toggle_roam_buffer_fixed = "<C-c>nb",
      },
@@ -451,6 +483,27 @@
 
 * API
 
+** Add Alias
+
+   roam.api.add_alias({opts})
+
+   Description:
+
+   Adds an alias to the node under cursor.
+
+   Parameters:
+
+   - {opts} optional table.
+     - alias: optional, if provided, added to the node under cursor, otherwise
+              prompts for an alias to add to the node under cursor.
+
+   Example:
+
+   #+begin_src lua
+   local roam = require("org-roam")
+   roam.api.add_alias({ alias = "My Alias" })
+   #+end_src
+
 ** Capture Node
 
    roam.api.capture_node({opts}, {cb})
@@ -463,10 +516,10 @@
    Parameters:
 
    - {opts} optional table.
-     - title: if provided, seeds the capture dialog with the title string.
-     - immediate: if true, skips displaying the capture buffer and instead
-                  populates a file using the immediate configuration. If
-                  title is also provided, it is used as the title of the
+     - title: optional, seeds the capture dialog with the title string.
+     - immediate: optional, if true, skips displaying the capture buffer and
+                  instead populates a file using the immediate configuration.
+                  If title is also provided, it is used as the title of the
                   created node.
    - {cb}   optional callback when finished. Is passed the id
             of the created node, or nil if capture was canceled.
@@ -517,7 +570,7 @@
    Parameters:
 
    - {opts} optional table.
-     - title: if provided, seeds the select dialog with the title string.
+     - title: optional, seeds the select dialog with the title string.
 
    Example:
 
@@ -546,13 +599,13 @@
    Parameters:
 
    - {opts} optional table.
-     - immediate: if true, skips displaying the capture buffer and instead
-                  populates a file using the immediate configuration. If
-                  title is also provided, it is used as the title of the
+     - immediate: optional, if true, skips displaying the capture buffer and
+                  instead populates a file using the immediate configuration.
+                  If title is also provided, it is used as the title of the
                   created node.
-     - title: if provided, seeds the select dialog with the title string.
-     - ranges: list of ranges to replace. Each range is comprised of the
-               following fields:
+     - title: optional, seeds the select dialog with the title string.
+     - ranges: optional, list of ranges to replace. Each range is comprised of
+               the following fields:
        - start_row: integer (one-indexed, inclusive)
        - start_col: integer (one-indexed, inclusive)
        - end_row: integer (one-indexed, inclusive)
@@ -582,8 +635,8 @@
    Parameters:
 
    - {opts} optional table.
-     - fixed: indicates that the node buffer should not update when the
-              node changes under the cursor. Takes the id of a node or
+     - fixed: optional, indicates that the node buffer should not update when
+              the node changes under the cursor. Takes the id of a node or
               a boolean value, which if true will leverage the select dialog
               to pick a node.
 
@@ -606,11 +659,13 @@
    Parameters:
 
    - {opts} optional table.
-     - id: string id of the node whose information will populate the list.
-           If not provided, will open a selection dialog to pick a node.
-     - backlinks: if true, show's the selected node's backlinks.
-     - links: if true, show's the selected node's links.
-     - show_preview: if true, loads a preview of content for each list item.
+     - id: optional, string id of the node whose information will populate
+           the list. If not provided, will open a selection dialog to pick
+           a node.
+     - backlinks: optional, if true, show's the selected node's backlinks.
+     - links: optional, if true, show's the selected node's links.
+     - show_preview: optional, if true, loads a preview of content for each
+                     list item.
 
    Example:
 
@@ -619,6 +674,29 @@
    roam.api.open_quickfix_list({ id = "1234", backlinks = true })
    #+end_src
 
+** Remove Alias
+
+   roam.api.remove_alias({opts})
+
+   Description:
+
+   Removes an alias from the node under cursor.
+
+   Parameters:
+
+   - {opts} optional table.
+     - alias: optional, if provided, removes from node under cursor, otherwise
+              prompts for an alias to remove from the node under cursor.
+     - all: optional, if true, will remove all aliases instead of just one.
+            Overrides removing =alias= from node under cursor.
+
+   Example:
+
+   #+begin_src lua
+   local roam = require("org-roam")
+   roam.api.remove_alias({ all = true })
+   #+end_src
+
 * Database
 
 ** Files
@@ -1075,9 +1153,9 @@
    Parameters:
 
    - {opts} optional table.
-     - force: if true, will reload each file and node regardless of whether
-              they have changed on disk. If false, only reloads pre-existing
-              files and nodes if they have changed.
+     - force: optional, if true, will reload each file and node regardless of
+              whether they have changed on disk. If false, only reloads
+              pre-existing files and nodes if they have changed.
 
    Example:
 

diff --git a/README.org b/README.org
@@ -9,7 +9,7 @@
 
 ** Installation
 
-   This plugin depends on [[https://github.com/nvim-orgmode/orgmode][nvim-orgmode/orgmode]] @ [[https://github.com/nvim-orgmode/orgmode/commit/68b6275bac3b321590b8a292576bea0f1766ccff][commit 68b6275]].
+   This plugin depends on [[https://github.com/nvim-orgmode/orgmode][nvim-orgmode/orgmode]] @ [[https://github.com/nvim-orgmode/orgmode/commit/5875037fa9c7c8e0abf29cd69510150355d248a0][commit 5875037]].
 
 *** lazy.nvim (recommended)
 
@@ -22,7 +22,7 @@
       dependencies = { 
         { 
           "nvim-orgmode/orgmode", 
-          commit = "68b6275bac3b321590b8a292576bea0f1766ccff",
+          commit = "5875037fa9c7c8e0abf29cd69510150355d248a0",
         },
       },
       config = function()
@@ -46,7 +46,7 @@
       requires = { 
         { 
           "nvim-orgmode/orgmode",
-          commit = "68b6275bac3b321590b8a292576bea0f1766ccff",
+          commit = "5875037fa9c7c8e0abf29cd69510150355d248a0",
         },
       },
       config = function()
@@ -61,16 +61,18 @@
 
 ** Bindings
 
-   | Name                     | Keybinding   | Description                                                             |
-   |--------------------------+--------------+-------------------------------------------------------------------------|
-   | capture                  | =<Leader>nc= | Opens org-roam capture window.                                          |
-   | complete_at_point        | =<Leader>n.= | Completes the node under cursor.                                        |
-   | find_node                | =<Leader>nf= | Finds node and moves to it, creating it if it does not exist.           |
-   | insert_node              | =<Leader>ni= | Inserts node at cursor position, creating it if it does not exist.      |
-   | insert_node_immediate    | =<Leader>nm= | Same as =insert_node=, but skips opening capture buffer.                |
-   | quickfix_backlinks       | =<Leader>nq= | Opens the quickfix menu for backlinks to the current node under cursor. |
-   | toggle_roam_buffer       | =<Leader>nl= | Toggles the org-roam node-view buffer for the node under cursor.        |
-   | toggle_roam_buffer_fixed | =<Leader>nb= | Toggles a fixed org-roam node-view buffer for a selected node.          |
+   | Name                     | Keybinding    | Description                                                             |
+   |--------------------------+---------------+-------------------------------------------------------------------------|
+   | add_alias                | =<Leader>naa= | Adds an alias to the node under cursor.                                 |
+   | capture                  | =<Leader>nc=  | Opens org-roam capture window.                                          |
+   | complete_at_point        | =<Leader>n.=  | Completes the node under cursor.                                        |
+   | find_node                | =<Leader>nf=  | Finds node and moves to it, creating it if it does not exist.           |
+   | insert_node              | =<Leader>ni=  | Inserts node at cursor position, creating it if it does not exist.      |
+   | insert_node_immediate    | =<Leader>nm=  | Same as =insert_node=, but skips opening capture buffer.                |
+   | quickfix_backlinks       | =<Leader>nq=  | Opens the quickfix menu for backlinks to the current node under cursor. |
+   | remove_alias             | =<Leader>nar= | Removes an alias from the node under cursor.                            |
+   | toggle_roam_buffer       | =<Leader>nl=  | Toggles the org-roam node-view buffer for the node under cursor.        |
+   | toggle_roam_buffer_fixed | =<Leader>nb=  | Toggles a fixed org-roam node-view buffer for a selected node.          |
 
 ** Documentation
 
@@ -92,6 +94,8 @@
        - Nodes that reference this node (see [[https://www.orgroam.com/manual.html#Refs][Refs]])
      - [ ] Implement *Unlinked references* widget for buffer
        - View nodes that contain text that match the nodes title/alias but are not linked
+     - [ ] Implement *Origin* widget for buffer (custom, not in Org Roam!)
+       - Displays the origin of the node as defined in =ROAM_ORIGIN=
    - [ ] Support [[https://www.orgroam.com/manual.html#Citations][citations]]
      - [ ] As of orgmode 9.5, *org-cite* is built-in and has the form *[cite:@key]*
      - [ ] Alongside *org-cite*, there is also support for [[https://github.com/jkitchin/org-ref][org-ref]] (v2 & v3),
@@ -104,6 +108,15 @@
      - [X] Implement *org-roam-node-find*
      - [X] Implement *org-roam-capture*
      - [X] Implement *org-roam-node-insert-immediate*
+   - [ ] Support origin (custom, not in Org Roam!)
+     - [ ] =ROAM_ORIGIN= available within node properties, containing org id
+     - [ ] Ability to query database for nodes with origin matching an id
+     - [ ] Keybinding to jump forward and backward across origins
+   - [X] Miscellaneous Roam functions
+     - [X] Implement *org-roam-alias-add*
+     - [X] Implement *org-roam-alias-remove*
+     - [ ] Implement *org-roam-origin-insert* (custom, not in Org Roam!)
+     - [ ] Implement *org-roam-origin-remove* (custom, not in Org Roam!)
    - [ ] Implement extensions
      - [ ] [[https://www.orgroam.com/manual.html#org_002droam_002ddailies][org-roam-dailies]]
      - [ ] [[https://www.orgroam.com/manual.html#org_002droam_002dexport][org-roam-export]]

diff --git a/lua/org-roam/api.lua b/lua/org-roam/api.lua
@@ -4,6 +4,7 @@
 -- Contains the API for the roam plugin.
 -------------------------------------------------------------------------------
 
+local AliasApi       = require("org-roam.api.alias")
 local CompletionApi  = require("org-roam.api.completion")
 local NodeApi        = require("org-roam.api.node")
 local open_quickfix  = require("org-roam.ui.quickfix")
@@ -12,11 +13,13 @@ local open_node_view = require("org-roam.ui.node-view")
 ---@class org-roam.Api
 local M              = {}
 
+M.add_alias          = AliasApi.add_alias
 M.capture_node       = NodeApi.capture
 M.complete_node      = CompletionApi.complete_node_under_cursor
 M.find_node          = NodeApi.find
 M.insert_node        = NodeApi.insert
 M.open_node_buffer   = open_node_view
 M.open_quickfix_list = open_quickfix
+M.remove_alias       = AliasApi.remove_alias
 
 return M