mirror of
https://github.com/org-roam/org-roam
synced 2025-08-17 13:33:31 -05:00
Compare commits
1 Commits
v2.1.0
...
migration/
| Author | SHA1 | Date | |
|---|---|---|---|
|
f5b8144c31 |
31
CHANGELOG.md
31
CHANGELOG.md
@@ -1,36 +1,9 @@
|
||||
# Changelog
|
||||
|
||||
## 2.1.0
|
||||
## 1.2.4 (TBD)
|
||||
|
||||
### Added
|
||||
- [#1709](https://github.com/org-roam/org-roam/pull/1709) added ability to specify default value in org-roam capture templates
|
||||
- [#1710](https://github.com/org-roam/org-roam/pull/1710) added `org-roam-extract-subtree`
|
||||
- [#1720](https://github.com/org-roam/org-roam/pull/1720) added `org-roam-db-update-on-save`
|
||||
- [#1758](https://github.com/org-roam/org-roam/pull/1758) added `org-roam-db-autosync-mode`, replacing `org-roam-setup` and `org-roam-teardown`
|
||||
|
||||
### Removed
|
||||
- [#1716](https://github.com/org-roam/org-roam/pull/1716) helper function `org-roam-get-keyword` is now obsolete: prefer `org-collect-keywords`
|
||||
|
||||
### Changed
|
||||
- [#1595](https://github.com/org-roam/org-roam/pull/1595), [#1724](https://github.com/org-roam/org-roam/pull/1724) Major refactoring and restructuring of the codebase
|
||||
- [#1655](https://github.com/org-roam/org-roam/pull/1655) improved org-roam contents preview
|
||||
- [#1741](https://github.com/org-roam/org-roam/pull/1741) expose `org-roam-capture-` keys in interactive commands
|
||||
- [#1786](https://github.com/org-roam/org-roam/pull/1786) org-roam-version now outputs commit hash if found
|
||||
- [#1788](https://github.com/org-roam/org-roam/pull/1788) the point is not moved if the node is already visited
|
||||
|
||||
### Fixed
|
||||
- [#1608](https://github.com/org-roam/org-roam/pull/1608) migration: empty ROAM_REFS are now removed
|
||||
- [#1609](https://github.com/org-roam/org-roam/pull/1609) migration: fixed file-link replacement
|
||||
- [#1653](https://github.com/org-roam/org-roam/pull/1653) migration: fixed tags migration
|
||||
- [#1694](https://github.com/org-roam/org-roam/pull/1694) core: nodes with no title are now skipped
|
||||
- [#1637](https://github.com/org-roam/org-roam/pull/1637) core: fix org-ref multi-cite links not being split
|
||||
- [#1651](https://github.com/org-roam/org-roam/pull/1651) core: fix org-roam-file-p crashing when there is no corresponding file
|
||||
- [#1705](https://github.com/org-roam/org-roam/pull/1705) core: fix for add/remove of file-level tags
|
||||
- [#1769](https://github.com/org-roam/org-roam/pull/1769) core: gracefully handle absence of `org-id-locations-file`
|
||||
- [#1713](https://github.com/org-roam/org-roam/pull/1713) capture: check for file-existence before template insertion
|
||||
- [#1725](https://github.com/org-roam/org-roam/pull/1725) db: always compute hash of encrypted file to prevent re-processing of encrypted files
|
||||
|
||||
## 2.0.0
|
||||
### Added
|
||||
- [#1396](https://github.com/org-roam/org-roam/pull/1396) add option to choose between prepending, appending, and omitting `roam_tags` in file completion
|
||||
- [#1270](https://github.com/org-roam/org-roam/pull/1270) capture: create OLP if it does not exist. Removes need for OLP setup in `:head`.
|
||||
- [#1353](https://github.com/org-roam/org-roam/pull/1353) support file-level property drawers
|
||||
|
||||
182
README.md
182
README.md
@@ -33,178 +33,38 @@ solution for anyone already using Org-mode for their personal wiki.
|
||||
|
||||
## Installation
|
||||
|
||||
Down below you will find basic installation instructions for how to quickly
|
||||
install `org-roam` using various environments for various purposes. For more
|
||||
detailed information, please read the [manual][docs].
|
||||
|
||||
### Using `package.el`
|
||||
<details>
|
||||
<summary>Toggle instuctions</summary>
|
||||
|
||||
You can install `org-roam` from [MELPA](https://melpa.org/) or [MELPA
|
||||
Stable](https://stable.melpa.org/) using `package.el`:
|
||||
You can install `org-roam` using `package.el`:
|
||||
|
||||
```
|
||||
M-x package-install RET org-roam RET
|
||||
```
|
||||
|
||||
Here's a very basic sample for configuration of `org-roam` using `use-package`:
|
||||
Here's a sample configuration with `use-package`:
|
||||
|
||||
```emacs-lisp
|
||||
(use-package org-roam
|
||||
:ensure t
|
||||
:custom
|
||||
(org-roam-directory (file-truename "/path/to/org-files/"))
|
||||
:bind (("C-c n l" . org-roam-buffer-toggle)
|
||||
("C-c n f" . org-roam-node-find)
|
||||
("C-c n g" . org-roam-graph)
|
||||
("C-c n i" . org-roam-node-insert)
|
||||
("C-c n c" . org-roam-capture)
|
||||
;; Dailies
|
||||
("C-c n j" . org-roam-dailies-capture-today))
|
||||
:config
|
||||
(org-roam-db-autosync-mode)
|
||||
;; If using org-roam-protocol
|
||||
(require 'org-roam-protocol))
|
||||
:ensure t
|
||||
:custom
|
||||
(org-roam-directory (file-truename "/path/to/org-files/"))
|
||||
:bind (("C-c n l" . org-roam-buffer-toggle)
|
||||
("C-c n f" . org-roam-node-find)
|
||||
("C-c n g" . org-roam-graph)
|
||||
("C-c n i" . org-roam-node-insert)
|
||||
("C-c n c" . org-roam-capture)
|
||||
;; Dailies
|
||||
("C-c n j" . org-roam-dailies-capture-today))
|
||||
:config
|
||||
(org-roam-setup)
|
||||
;; If using org-roam-protocol
|
||||
(require 'org-roam-protocol))
|
||||
```
|
||||
|
||||
Note that the `file-truename` function is only necessary when you use symbolic
|
||||
link to `org-roam-directory`. Org-roam won't automatically resolve symbolic link
|
||||
to the directory.
|
||||
</details>
|
||||
The `file-truename` function is only necessary when you use symbolic links
|
||||
inside `org-roam-directory`: Org-roam does not resolve symbolic links.
|
||||
|
||||
### Using `straight.el`
|
||||
<details>
|
||||
<summary>Toggle instuctions</summary>
|
||||
|
||||
Installation from MELPA or MELPA Stable using `straight.el`:
|
||||
|
||||
```emacs-lisp
|
||||
(straight-use-package 'org-roam)
|
||||
```
|
||||
|
||||
Or with `use-package`:
|
||||
|
||||
```emacs-lisp
|
||||
(use-package org-roam
|
||||
:straight t
|
||||
...)
|
||||
```
|
||||
|
||||
If you need to install the package directly from the source repository, instead
|
||||
of from MELPA, the next sample shows how to do so:
|
||||
|
||||
```emacs-lisp
|
||||
(use-package org-roam
|
||||
:straight (:host github :repo "org-roam/org-roam"
|
||||
:files (:defaults "extensions/*"))
|
||||
...)
|
||||
```
|
||||
|
||||
If you plan to use your own local fork for the development and contribution, the
|
||||
next sample will get you there:
|
||||
|
||||
```emacs-lisp
|
||||
(use-package org-roam
|
||||
:straight (:local-repo "/path/to/org-roam-fork"
|
||||
:files (:defaults "extensions/*")
|
||||
:build (:not compile))
|
||||
...)
|
||||
```
|
||||
</details>
|
||||
|
||||
### Using Doom Emacs
|
||||
<details>
|
||||
<summary>Toggle instuctions</summary>
|
||||
|
||||
Doom's `:lang org` module comes with support for `org-roam`, but it's not
|
||||
enabled by default. To activate it pass `+roam2` flag to `org` module in your
|
||||
`$DOOMDIR/init.el` (e.g. `(org +roam2)`), save the file and run `doom sync -u`
|
||||
in your shell.
|
||||
|
||||
To provide better stability, Doom pins the package to a specific commit. If you
|
||||
need to unpin it *(not recommended doing that, request Doom to bump the package
|
||||
instead)* use the next in your `packages.el`:
|
||||
|
||||
```emacs-lisp
|
||||
(unpin! org-roam)
|
||||
```
|
||||
|
||||
If for some reasons you want to use a different recipe for `org-roam`, you can
|
||||
use the next form in your `packages.el` to install the package from a recipe
|
||||
repository (e.g. MELPA):
|
||||
|
||||
```emacs-lisp
|
||||
(package! org-roam)
|
||||
```
|
||||
|
||||
You can pass `:pin "commit hash"` to pin the package to a specific commit.
|
||||
|
||||
With the next sample you can install the package directly from the source
|
||||
repository:
|
||||
|
||||
```emacs-lisp
|
||||
(package! org-roam
|
||||
:recipe (:host github :repo "org-roam/org-roam"
|
||||
:files (:defaults "extensions/*")))
|
||||
```
|
||||
|
||||
And if you plan to use your own local fork for the development or contribution,
|
||||
the next sample will get you there:
|
||||
|
||||
```emacs-lisp
|
||||
(package! org-roam
|
||||
:recipe (:local-repo "/path/to/org-roam-fork"
|
||||
:files (:defaults "extensions/*")
|
||||
:build (:not compile)))
|
||||
```
|
||||
</details>
|
||||
|
||||
### Without a package manager
|
||||
<details>
|
||||
<summary>Toggle instructions</summary>
|
||||
|
||||
To install the package without using a package manager you have the next two
|
||||
options:
|
||||
|
||||
1. Install the package by cloning it with `git` from the source repository.
|
||||
2. Or install the package by downloading the latest [release
|
||||
version](https://github.com/org-roam/org-roam/releases).
|
||||
|
||||
In both of the cases you will need to ensure that you have all the required
|
||||
dependencies. These include:
|
||||
|
||||
- dash
|
||||
- f
|
||||
- s
|
||||
- org (9.4 is the minimal required version!)
|
||||
- emacsql
|
||||
- emacsql-sqlite
|
||||
- magit-section
|
||||
- filenotify-recursive
|
||||
|
||||
After installing the package, you will need to properly setup `load-path` to the
|
||||
package:
|
||||
|
||||
``` emacs-lisp
|
||||
(add-to-list 'load-path "/path/to/org-roam/")
|
||||
(add-to-list 'load-path "/path/to-org-roam/extensions/")
|
||||
```
|
||||
|
||||
After which you should be able to resolve `(require 'org-roam)` call without any
|
||||
problems.
|
||||
|
||||
Org-roam also comes with `.texi` files to integrate with Emacs' built-in Info
|
||||
system. Read the manual to find more details for how to install them manually.
|
||||
</details>
|
||||
|
||||
## Getting Started
|
||||
|
||||
[David Wilson](https://github.com/daviwil) of [System
|
||||
Crafters](https://www.youtube.com/c/SystemCrafters) has produced an introductory
|
||||
video that covers the basic commands:
|
||||
|
||||
[](https://www.youtube.com/watch?v=AyhPmypHDEw)
|
||||
Org-roam requires sqlite to function. Org-roam optionally uses Graphviz for
|
||||
graph-related functionality. It is recommended to install PCRE-enabled ripgrep
|
||||
for better performance and extended functionality.
|
||||
|
||||
## Getting Help
|
||||
|
||||
|
||||
15
default.mk
15
default.mk
@@ -44,17 +44,16 @@ HTMLDIRS = $(PACKAGES)
|
||||
PDFFILES = $(addsuffix .pdf,$(PACKAGES))
|
||||
EPUBFILES = $(addsuffix .epub,$(PACKAGES))
|
||||
|
||||
ELS = org-roam.el
|
||||
ELS = org-roam-buffer.el
|
||||
ELS += org-roam-capture.el
|
||||
ELS += org-roam-compat.el
|
||||
ELS += org-roam-completion.el
|
||||
ELS += org-roam-dailies.el
|
||||
ELS += org-roam-db.el
|
||||
ELS += org-roam-mode.el
|
||||
ELS += org-roam-node.el
|
||||
ELS += org-roam-utils.el
|
||||
ELS += extensions/org-roam-dailies.el
|
||||
ELS += extensions/org-roam-graph.el
|
||||
ELS += extensions/org-roam-overlay.el
|
||||
ELS += extensions/org-roam-protocol.el
|
||||
ELS += org-roam.el
|
||||
ELS += org-roam-graph.el
|
||||
ELS += org-roam-macs.el
|
||||
ELS += org-roam-protocol.el
|
||||
ELCS = $(ELS:.el=.elc)
|
||||
ELMS = org-roam.el $(filter-out $(addsuffix .el,$(PACKAGES)),$(ELS))
|
||||
ELGS = org-roam-autoloads.el org-roam-version.el
|
||||
|
||||
@@ -116,8 +116,8 @@
|
||||
<div class="row">
|
||||
<a
|
||||
class="content footer-links"
|
||||
href="https://github.com/org-roam/org-roam-ui"
|
||||
>org-roam-ui</a
|
||||
href="https://github.com/org-roam/org-roam-server"
|
||||
>org-roam-server</a
|
||||
>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
173
doc/org-roam.org
173
doc/org-roam.org
@@ -8,13 +8,13 @@
|
||||
#+texinfo_dir_category: Emacs
|
||||
#+texinfo_dir_title: Org-roam: (org-roam).
|
||||
#+texinfo_dir_desc: Roam Research for Emacs.
|
||||
#+subtitle: for version 2.1.0
|
||||
#+subtitle: for version 2.0.0
|
||||
|
||||
#+options: H:4 num:3 toc:nil creator:t ':t
|
||||
#+property: header-args :eval never
|
||||
#+texinfo: @noindent
|
||||
|
||||
This manual is for Org-roam version 2.1.0.
|
||||
This manual is for Org-roam version 2.0.0.
|
||||
|
||||
#+BEGIN_QUOTE
|
||||
Copyright (C) 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
@@ -67,7 +67,7 @@ Org-roam provides these benefits over other tooling:
|
||||
|
||||
Org-roam is a tool that will appear unfriendly to anyone unfamiliar with Emacs
|
||||
and Org-mode, but it is also extremely powerful to those willing to put effort
|
||||
in mastering the intricacies. Org-roam stands on the shoulders of giants. Emacs
|
||||
inn mastering the intricacies. Org-roam stands on the shoulders of giants. Emacs
|
||||
was first created in 1976, and remains the tool of choice for many for editing
|
||||
text and designing textual interfaces. The malleability of Emacs allowed the
|
||||
creation of Org-mode, an all-purpose plain-text system for maintaining TODO
|
||||
@@ -134,7 +134,7 @@ A slip-box requires a method for quickly capturing ideas. These are called
|
||||
*fleeting notes*: they are simple reminders of information or ideas that will
|
||||
need to be processed later on, or trashed. This is typically accomplished using
|
||||
~org-capture~ (see info:org#Capture), or using Org-roam's daily notes
|
||||
functionality (see [[*Org-roam Dailies][Org-roam Dailies]]). This provides a central inbox for collecting
|
||||
functionality (see [[id:4eae8552-95e1-4e4a-b7b7-2c53433730ea][Org-roam Dailies]]). This provides a central inbox for collecting
|
||||
thoughts, to be processed later into permanent notes.
|
||||
|
||||
*Permanent notes*
|
||||
@@ -198,6 +198,17 @@ using:
|
||||
M-x package-install RET org-roam RET
|
||||
#+END_EXAMPLE
|
||||
|
||||
** Installing from Apt
|
||||
|
||||
Users of Debian 11 or later or Ubuntu 20.10 or later can simply install Org-roam
|
||||
using Apt:
|
||||
|
||||
#+BEGIN_SRC bash
|
||||
apt-get install elpa-org-roam
|
||||
#+END_SRC
|
||||
|
||||
Org-roam will then be autoloaded into Emacs.
|
||||
|
||||
** Installing from Source
|
||||
|
||||
You may install Org-roam directly from the repository on [[https://github.com/org-roam/org-roam][GitHub]] if you like.
|
||||
@@ -236,7 +247,6 @@ dependencies that it requires. These include:
|
||||
- org
|
||||
- emacsql
|
||||
- emacsql-sqlite
|
||||
- magit-section
|
||||
|
||||
You can install this manually as well, or get the latest version from MELPA. You
|
||||
may wish to use [[https://github.com/jwiegley/use-package][use-package]], [[https://github.com/raxod502/straight.el][straight.el]] to help manage this.
|
||||
@@ -308,7 +318,7 @@ is to use [[https://www.msys2.org/][MSYS2]] as at the time of this writing:
|
||||
Note that you do not need to manually set the PATH for MSYS2; the
|
||||
installer automatically takes care of it for you.
|
||||
|
||||
4. Open Emacs and call ~M-x org-roam-db-autosync-mode~
|
||||
4. Open Emacs and call ~M-x org-roam-setup~
|
||||
|
||||
This will automatically start compiling ~emacsql-sqlite~; you should see a
|
||||
message in minibuffer. It may take a while until compilation completes. Once
|
||||
@@ -376,19 +386,45 @@ The ~file-truename~ function is only necessary when you use symbolic links
|
||||
inside ~org-roam-directory~: Org-roam does not resolve symbolic links.
|
||||
|
||||
Next, we setup Org-roam to run functions on file changes to maintain cache
|
||||
consistency. This is achieved by running ~M-x org-roam-db-autosync-mode~. To
|
||||
ensure that Org-roam is available on startup, place this in your Emacs
|
||||
configuration:
|
||||
consistency. This is achieved by running ~M-x org-roam-setup~. To ensure that
|
||||
Org-roam is available on startup, place this in your Emacs configuration:
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(org-roam-db-autosync-mode)
|
||||
(require 'org-roam)
|
||||
(org-roam-setup)
|
||||
#+end_src
|
||||
|
||||
To build the cache manually, run ~M-x org-roam-db-sync~. Cache builds may
|
||||
take a while the first time, but subsequent builds are often instantaneous
|
||||
because they only reprocess modified files.
|
||||
|
||||
** Creating and Linking Nodes
|
||||
** Customizing Node Caching
|
||||
|
||||
By default, all nodes (any headline or file with an ID) are cached by Org-roam.
|
||||
There are instances where you may want to have headlines with ID, but not have
|
||||
them cached by Org-roam.
|
||||
|
||||
To exclude a headline from the Org-roam database, set the ~ROAM_EXCLUDE~
|
||||
property to a non-nil value. For example:
|
||||
|
||||
#+begin_src org
|
||||
,* Foo
|
||||
:PROPERTIES:
|
||||
:ID: foo
|
||||
:ROAM_EXCLUDE: t
|
||||
:END:
|
||||
#+end_src
|
||||
|
||||
One can also set ~org-roam-db-node-include-function~. For example, to exclude
|
||||
all headlines with the ~ATTACH~ tag from the Org-roam database, one can set:
|
||||
|
||||
#+begin_src org
|
||||
(setq org-roam-db-node-include-function
|
||||
(lambda ()
|
||||
(not (member "ATTACH" (org-get-tags)))))
|
||||
#+end_src
|
||||
|
||||
** TODO Creating and Linking Nodes
|
||||
|
||||
Org-roam makes it easy to create notes and link them together. There are 2 main
|
||||
functions for creating nodes:
|
||||
@@ -415,64 +451,25 @@ node. If you instead entered a title that does not exist, you will once again be
|
||||
brought through the node creation process.
|
||||
|
||||
One can also conveniently insert links via the completion-at-point functions
|
||||
Org-roam provides (see [[*Completion][Completion]]).
|
||||
|
||||
* Customizing Node Caching
|
||||
** What to cache
|
||||
|
||||
By default, all nodes (any headline or file with an ID) are cached by Org-roam.
|
||||
There are instances where you may want to have headlines with ID, but not have
|
||||
them cached by Org-roam.
|
||||
|
||||
To exclude a headline from the Org-roam database, set the ~ROAM_EXCLUDE~
|
||||
property to a non-nil value. For example:
|
||||
|
||||
#+begin_src org
|
||||
,* Foo
|
||||
:PROPERTIES:
|
||||
:ID: foo
|
||||
:ROAM_EXCLUDE: t
|
||||
:END:
|
||||
#+end_src
|
||||
|
||||
One can also set ~org-roam-db-node-include-function~. For example, to exclude
|
||||
all headlines with the ~ATTACH~ tag from the Org-roam database, one can set:
|
||||
|
||||
#+begin_src org
|
||||
(setq org-roam-db-node-include-function
|
||||
(lambda ()
|
||||
(not (member "ATTACH" (org-get-tags)))))
|
||||
#+end_src
|
||||
|
||||
** When to cache
|
||||
|
||||
By default, Org-roam is eager in caching: each time an Org-roam file is modified
|
||||
and saved, it updates the database for the corresponding file. This keeps the
|
||||
database up-to-date, causing the least surprise when using the interactive
|
||||
commands.
|
||||
|
||||
However, depending on how large your Org files are, database updating can be a
|
||||
slow operation. You can disable the automatic updating of the database by
|
||||
setting ~org-roam-db-update-on-save~ to ~nil~.
|
||||
|
||||
- Variable: org-roam-db-update-on-save
|
||||
|
||||
If t, update the Org-roam database upon saving the file. Disable this if your
|
||||
files are large and updating the database is slow.
|
||||
Org-roam provides (see [[id:70083bfd-d1e3-42b9-bf83-5b05708791c0][Completion]]).
|
||||
|
||||
* The Org-roam Buffer
|
||||
|
||||
Org-roam provides the Org-roam buffer: an interface to view relationships with
|
||||
other notes (backlinks, reference links, unlinked references etc.). There are
|
||||
two main commands to use here:
|
||||
two main functions to use here:
|
||||
|
||||
- ~org-roam-buffer~: Launch an Org-roam buffer for the current node at point.
|
||||
- ~org-roam-buffer-toggle~: Launch an Org-roam buffer that tracks the node
|
||||
currently at point. This means that the content of the buffer changes as the
|
||||
point is moved, if necessary.
|
||||
- ~org-roam-buffer-display-dedicated~: Launch an Org-roam buffer for a specific
|
||||
node without visiting its file. Unlike ~org-roam-buffer-toggle~ you can have
|
||||
multiple such buffers and their content won't be automatically replaced with a
|
||||
new node at point.
|
||||
|
||||
Use ~org-roam-buffer-toggle~ when you want wish for the Org-roam buffer to
|
||||
buffer, call ~M-x org-roam-buffer~.
|
||||
|
||||
- Function: org-roam-buffer
|
||||
|
||||
Launch an Org-roam buffer for the current node at point.
|
||||
|
||||
To bring up a buffer that tracks the current node at point, call ~M-x
|
||||
org-roam-buffer-toggle~.
|
||||
@@ -481,13 +478,6 @@ org-roam-buffer-toggle~.
|
||||
|
||||
Toggle display of the ~org-roam-buffer~.
|
||||
|
||||
To bring up a buffer that's dedicated for a specific node, call ~M-x
|
||||
org-roam-buffer-display-dedicated~.
|
||||
|
||||
- Function: org-roam-buffer-display-dedicated
|
||||
|
||||
Launch node dedicated Org-roam buffer without visiting the node itself.
|
||||
|
||||
** Navigating the Org-roam Buffer
|
||||
|
||||
The Org-roam buffer uses ~magit-section~, making the typical ~magit-section~
|
||||
@@ -496,9 +486,9 @@ keybindings available. Here are several of the more useful ones:
|
||||
- ~M-{N}~: ~magit-section-show-level-{N}-all~
|
||||
- ~n~: ~magit-section-forward~
|
||||
-~<TAB>~: ~magit-section-toggle~
|
||||
- ~<RET>~: ~org-roam-buffer-visit-thing~
|
||||
- ~<RET>~: ~org-roam-visit-thing~
|
||||
|
||||
~org-roam-buffer-visit-thing~ is a placeholder command, that is replaced by
|
||||
~org-roam-visit-thing~ is a placeholder command, that is replaced by
|
||||
section-specific commands such as ~org-roam-node-visit~.
|
||||
|
||||
** Configuring what is displayed in the buffer
|
||||
@@ -510,10 +500,10 @@ There are currently 3 provided widget types:
|
||||
- Unlinked references :: View nodes that contain text that match the nodes
|
||||
title/alias but are not linked
|
||||
|
||||
To configure what sections are displayed in the buffer, set ~org-roam-mode-section-functions~.
|
||||
To configure what sections are displayed in the buffer, set ~org-roam-mode-sections~.
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(setq org-roam-mode-section-functions
|
||||
(setq org-roam-mode-sections
|
||||
(list #'org-roam-backlinks-section
|
||||
#'org-roam-reflinks-section
|
||||
;; #'org-roam-unlinked-references-section
|
||||
@@ -647,6 +637,9 @@ Org-roam also provides some functions to add or remove refs.
|
||||
Remove a ref from the node at point.
|
||||
|
||||
* Completion
|
||||
:PROPERTIES:
|
||||
:ID: 70083bfd-d1e3-42b9-bf83-5b05708791c0
|
||||
:END:
|
||||
|
||||
Completions for Org-roam are provided via ~completion-at-point~. Org-roam
|
||||
currently provides completions in two scenarios:
|
||||
@@ -854,7 +847,7 @@ graph navigable.
|
||||
|
||||
** The roam-ref protocol
|
||||
|
||||
This protocol finds or creates a new note with a given ~ROAM_REFS~:
|
||||
This protocol finds or creates a new note with a given ~roam_key~:
|
||||
|
||||
[[file:images/roam-ref.gif]]
|
||||
|
||||
@@ -878,7 +871,8 @@ or as a keybinding in ~qutebrowser~ in , using the ~config.py~ file (see
|
||||
#+END_SRC
|
||||
|
||||
where ~template~ is the template key for a template in
|
||||
~org-roam-capture-ref-templates~ (see [[*The Templating System][The Templating System]]).
|
||||
~org-roam-capture-ref-templates~ (see [[*The Templating System][The Templating System]]). These templates
|
||||
should contain a ~#+roam_key: ${ref}~ in it.
|
||||
|
||||
* The Templating System
|
||||
|
||||
@@ -939,23 +933,6 @@ strings. ~${foo}~'s substitution is performed as follows:
|
||||
3. Else look up ~org-roam-capture--info~ for ~foo~. This is an internal variable
|
||||
that is set before the capture process begins.
|
||||
4. If none of the above applies, read a string using ~completing-read~.
|
||||
a. Org-roam also provides the ~${foo=default_val}~ syntax, where if a default
|
||||
value is provided, will be the initial value for the ~foo~ key during
|
||||
minibuffer completion.
|
||||
|
||||
One can check the list of available keys for nodes by inspecting the
|
||||
~org-roam-node~ struct. At the time of writing, it is:
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(cl-defstruct (org-roam-node (:constructor org-roam-node-create)
|
||||
(:copier nil))
|
||||
"A heading or top level file with an assigned ID property."
|
||||
file file-hash file-atime file-mtime
|
||||
id level point todo priority scheduled deadline title properties olp
|
||||
tags aliases refs)
|
||||
#+end_src
|
||||
|
||||
This makes ~${file}~, ~${file-hash}~ etc. all valid substitutions.
|
||||
|
||||
* Graphing
|
||||
|
||||
@@ -1030,6 +1007,9 @@ for customizable options.
|
||||
Example: ~'(("dir" . "back"))~
|
||||
|
||||
* Org-roam Dailies
|
||||
:PROPERTIES:
|
||||
:ID: 4eae8552-95e1-4e4a-b7b7-2c53433730ea
|
||||
:END:
|
||||
|
||||
Org-roam provides journaling capabilities akin to
|
||||
Org-journal with ~org-roam-dailies~.
|
||||
@@ -1245,7 +1225,7 @@ documents (PDF, EPUB etc.) within Org-mode.
|
||||
|
||||
For example, though helm-bibtex provides the ability to visit notes for
|
||||
bibliographic entries, org-roam-bibtex extends it with the ability to visit the
|
||||
file with the right ~ROAM_REFS~.
|
||||
file with the right =#+ROAM_KEYS=.
|
||||
|
||||
** Spaced Repetition
|
||||
|
||||
@@ -1293,13 +1273,6 @@ are the solutions:
|
||||
set ~ivy-use-selectable-prompt~ to ~t~, so that "bar" is now selectable.
|
||||
- Helm :: Org-roam should provide a selectable "[?] bar" candidate at the top of
|
||||
the candidate list.
|
||||
** How can I stop Org-roam from creating IDs everywhere?
|
||||
|
||||
Other than the interactive commands that Org-roam provides, Org-roam does not
|
||||
create IDs everywhere. If you are noticing that IDs are being created even when
|
||||
you don't want them to be (e.g. when tangling an Org file), check the value you
|
||||
have set for ~org-id-link-to-org-use-id~: setting it to ~'create-if-interactive~
|
||||
is a popular option.
|
||||
|
||||
* Migrating from Org-roam v1
|
||||
|
||||
@@ -1410,7 +1383,7 @@ method to access nodes is ~org-roam-node-at-point~ and ~org-roam-node-read~:
|
||||
is a function to filter out nodes: it takes a single argument (an
|
||||
~org-roam-node~), and when nil is returned the node will be
|
||||
filtered out.
|
||||
SORT-FN is a function to sort nodes. See ~org-roam-node-read-sort-by-file-mtime~
|
||||
SORT-FN is a function to sort nodes. See ~org-roam-node-sort-by-file-mtime~
|
||||
for an example sort function.
|
||||
If REQUIRE-MATCH, the minibuffer prompt will require a match.
|
||||
|
||||
@@ -1442,7 +1415,7 @@ instead. The exposed function to be used in extensions is ~org-roam-capture-~:
|
||||
|
||||
Main entry point.
|
||||
GOTO and KEYS correspond to `org-capture' arguments.
|
||||
INFO is a plist for filling up Org-roam's capture templates.
|
||||
INFO is an alist for filling up Org-roam's capture templates.
|
||||
NODE is an `org-roam-node' construct containing information about the node.
|
||||
PROPS is a plist containing additional Org-roam properties for each template.
|
||||
TEMPLATES is a list of org-roam templates.
|
||||
|
||||
@@ -31,7 +31,7 @@ General Public License for more details.
|
||||
@finalout
|
||||
@titlepage
|
||||
@title Org-roam User Manual
|
||||
@subtitle for version 2.1.0
|
||||
@subtitle for version 2.0.0
|
||||
@author Jethro Kuan
|
||||
@page
|
||||
@vskip 0pt plus 1filll
|
||||
@@ -44,7 +44,7 @@ General Public License for more details.
|
||||
|
||||
@noindent
|
||||
|
||||
This manual is for Org-roam version 2.1.0.
|
||||
This manual is for Org-roam version 2.0.0.
|
||||
|
||||
@quotation
|
||||
Copyright (C) 2020-2021 Jethro Kuan <jethrokuan95@@gmail.com>
|
||||
@@ -67,7 +67,6 @@ General Public License for more details.
|
||||
* A Brief Introduction to the Zettelkasten Method::
|
||||
* Installation::
|
||||
* Getting Started::
|
||||
* Customizing Node Caching::
|
||||
* The Org-roam Buffer::
|
||||
* Node Properties::
|
||||
* Completion::
|
||||
@@ -93,6 +92,7 @@ General Public License for more details.
|
||||
Installation
|
||||
|
||||
* Installing from MELPA::
|
||||
* Installing from Apt::
|
||||
* Installing from Source::
|
||||
* Installation Troubleshooting::
|
||||
|
||||
@@ -105,13 +105,9 @@ Getting Started
|
||||
* The Org-roam Node::
|
||||
* Links between Nodes::
|
||||
* Setting up Org-roam::
|
||||
* Customizing Node Caching::
|
||||
* Creating and Linking Nodes::
|
||||
|
||||
Customizing Node Caching
|
||||
|
||||
* What to cache::
|
||||
* When to cache::
|
||||
|
||||
The Org-roam Buffer
|
||||
|
||||
* Navigating the Org-roam Buffer::
|
||||
@@ -178,7 +174,6 @@ FAQ
|
||||
* How do I have more than one Org-roam directory?::
|
||||
* How do I migrate from Roam Research?::
|
||||
* How do I create a note whose title already matches one of the candidates?::
|
||||
* How can I stop Org-roam from creating IDs everywhere?::
|
||||
|
||||
Developer's Guide to Org-roam
|
||||
|
||||
@@ -342,6 +337,7 @@ development repository.
|
||||
|
||||
@menu
|
||||
* Installing from MELPA::
|
||||
* Installing from Apt::
|
||||
* Installing from Source::
|
||||
* Installation Troubleshooting::
|
||||
@end menu
|
||||
@@ -397,6 +393,18 @@ using:
|
||||
M-x package-install RET org-roam RET
|
||||
@end example
|
||||
|
||||
@node Installing from Apt
|
||||
@section Installing from Apt
|
||||
|
||||
Users of Debian 11 or later or Ubuntu 20.10 or later can simply install Org-roam
|
||||
using Apt:
|
||||
|
||||
@example
|
||||
apt-get install elpa-org-roam
|
||||
@end example
|
||||
|
||||
Org-roam will then be autoloaded into Emacs.
|
||||
|
||||
@node Installing from Source
|
||||
@section Installing from Source
|
||||
|
||||
@@ -448,9 +456,6 @@ emacsql
|
||||
|
||||
@item
|
||||
emacsql-sqlite
|
||||
|
||||
@item
|
||||
magit-section
|
||||
@end itemize
|
||||
|
||||
You can install this manually as well, or get the latest version from MELPA@. You
|
||||
@@ -550,7 +555,7 @@ installer automatically takes care of it for you.
|
||||
|
||||
@itemize
|
||||
@item
|
||||
Open Emacs and call @code{M-x org-roam-db-autosync-mode}
|
||||
Open Emacs and call @code{M-x org-roam-setup}
|
||||
|
||||
This will automatically start compiling @code{emacsql-sqlite}; you should see a
|
||||
@end itemize
|
||||
@@ -567,6 +572,7 @@ your Emacs configuration folder like this:
|
||||
* The Org-roam Node::
|
||||
* Links between Nodes::
|
||||
* Setting up Org-roam::
|
||||
* Customizing Node Caching::
|
||||
* Creating and Linking Nodes::
|
||||
@end menu
|
||||
|
||||
@@ -637,20 +643,47 @@ The @code{file-truename} function is only necessary when you use symbolic links
|
||||
inside @code{org-roam-directory}: Org-roam does not resolve symbolic links.
|
||||
|
||||
Next, we setup Org-roam to run functions on file changes to maintain cache
|
||||
consistency. This is achieved by running @code{M-x org-roam-db-autosync-mode~}.
|
||||
To ensure that Org-roam is available on startup, place this in your Emacs
|
||||
configuration:
|
||||
consistency. This is achieved by running @code{M-x org-roam-setup}. To ensure that
|
||||
Org-roam is available on startup, place this in your Emacs configuration:
|
||||
|
||||
@lisp
|
||||
(org-roam-db-autosync-mode)
|
||||
(require 'org-roam)
|
||||
(org-roam-setup)
|
||||
@end lisp
|
||||
|
||||
To build the cache manually, run @code{M-x org-roam-db-sync}. Cache builds may
|
||||
To build the cache manually, run @code{M-x org-roam-db-build-cache}. Cache builds may
|
||||
take a while the first time, but subsequent builds are often instantaneous
|
||||
because they only reprocess modified files.
|
||||
|
||||
@node Customizing Node Caching
|
||||
@section Customizing Node Caching
|
||||
|
||||
By default, all nodes (any headline or file with an ID) are cached by Org-roam.
|
||||
There are instances where you may want to have headlines with ID, but not have
|
||||
them cached by Org-roam.
|
||||
|
||||
To exclude a headline from the Org-roam database, set the @code{ROAM_EXCLUDE}
|
||||
property to a non-nil value. For example:
|
||||
|
||||
@example
|
||||
* Foo
|
||||
:PROPERTIES:
|
||||
:ID: foo
|
||||
:ROAM_EXCLUDE: t
|
||||
:END:
|
||||
@end example
|
||||
|
||||
One can also set @code{org-roam-db-node-include-function}. For example, to exclude
|
||||
all headlines with the @code{ATTACH} tag from the Org-roam database, one can set:
|
||||
|
||||
@example
|
||||
(setq org-roam-db-node-include-function
|
||||
(lambda ()
|
||||
(not (member "ATTACH" (org-get-tags)))))
|
||||
@end example
|
||||
|
||||
@node Creating and Linking Nodes
|
||||
@section Creating and Linking Nodes
|
||||
@section @strong{TODO} Creating and Linking Nodes
|
||||
|
||||
Org-roam makes it easy to create notes and link them together. There are 2 main
|
||||
functions for creating nodes:
|
||||
@@ -686,79 +719,31 @@ brought through the node creation process.
|
||||
One can also conveniently insert links via the completion-at-point functions
|
||||
Org-roam provides (see @ref{Completion}).
|
||||
|
||||
@node Customizing Node Caching
|
||||
@chapter Customizing Node Caching
|
||||
|
||||
@menu
|
||||
* What to cache::
|
||||
* When to cache::
|
||||
@end menu
|
||||
|
||||
@node What to cache
|
||||
@section What to cache
|
||||
|
||||
By default, all nodes (any headline or file with an ID) are cached by Org-roam.
|
||||
There are instances where you may want to have headlines with ID, but not have
|
||||
them cached by Org-roam.
|
||||
|
||||
To exclude a headline from the Org-roam database, set the @code{ROAM_EXCLUDE}
|
||||
property to a non-nil value. For example:
|
||||
|
||||
@example
|
||||
* Foo
|
||||
:PROPERTIES:
|
||||
:ID: foo
|
||||
:ROAM_EXCLUDE: t
|
||||
:END:
|
||||
@end example
|
||||
|
||||
One can also set @code{org-roam-db-node-include-function}. For example, to exclude
|
||||
all headlines with the @code{ATTACH} tag from the Org-roam database, one can set:
|
||||
|
||||
@example
|
||||
(setq org-roam-db-node-include-function
|
||||
(lambda ()
|
||||
(not (member "ATTACH" (org-get-tags)))))
|
||||
@end example
|
||||
|
||||
@node When to cache
|
||||
@section When to cache
|
||||
|
||||
By default, Org-roam is eager in caching: each time an Org-roam file is modified
|
||||
and saved, it updates the database for the corresponding file. This keeps the
|
||||
database up-to-date, causing the least surprise when using the interactive
|
||||
commands.
|
||||
|
||||
However, depending on how large your Org files are, database updating can be a
|
||||
slow operation. You can disable the automatic updating of the database by
|
||||
setting @code{org-roam-db-update-on-save} to @code{nil}.
|
||||
|
||||
@defvar org-roam-db-update-on-save
|
||||
@end defvar
|
||||
|
||||
If t, update the Org-roam database upon saving the file. Disable this if your
|
||||
files are large and updating the database is slow.
|
||||
|
||||
@node The Org-roam Buffer
|
||||
@chapter The Org-roam Buffer
|
||||
|
||||
Org-roam provides the Org-roam buffer: an interface to view relationships with
|
||||
other notes (backlinks, reference links, unlinked references etc.). There are
|
||||
two main commands to use here:
|
||||
two main functions to use here:
|
||||
|
||||
@itemize
|
||||
@item
|
||||
@code{org-roam-buffer}: Launch an Org-roam buffer for the current node at point.
|
||||
|
||||
@item
|
||||
@code{org-roam-buffer-toggle}: Launch an Org-roam buffer that tracks the node
|
||||
currently at point. This means that the content of the buffer changes as the
|
||||
point is moved, if necessary.
|
||||
|
||||
@item
|
||||
@code{org-roam-buffer-display-dedicated}: Launch an Org-roam buffer for a specific
|
||||
node without visiting its file. Unlike @code{org-roam-buffer-toggle} you can have
|
||||
multiple such buffers and their content won't be automatically replaced with a
|
||||
new node at point.
|
||||
@end itemize
|
||||
|
||||
Use @code{org-roam-buffer-toggle} when you want wish for the Org-roam buffer to
|
||||
buffer, call @code{M-x org-roam-buffer}.
|
||||
|
||||
@defun org-roam-buffer
|
||||
|
||||
Launch an Org-roam buffer for the current node at point.
|
||||
@end defun
|
||||
|
||||
To bring up a buffer that tracks the current node at point, call @code{M-x
|
||||
org-roam-buffer-toggle}.
|
||||
|
||||
@@ -767,14 +752,6 @@ org-roam-buffer-toggle}.
|
||||
Toggle display of the @code{org-roam-buffer}.
|
||||
@end defun
|
||||
|
||||
To bring up a buffer that's dedicated for a specific node, call @code{M-x
|
||||
org-roam-buffer-display-dedicated}.
|
||||
|
||||
@defun org-roam-buffer-display-dedicated
|
||||
|
||||
Launch node dedicated Org-roam buffer without visiting the node itself.
|
||||
@end defun
|
||||
|
||||
@menu
|
||||
* Navigating the Org-roam Buffer::
|
||||
* Configuring what is displayed in the buffer::
|
||||
@@ -798,10 +775,10 @@ keybindings available. Here are several of the more useful ones:
|
||||
-@code{<TAB>}: @code{magit-section-toggle}
|
||||
@itemize
|
||||
@item
|
||||
@code{<RET>}: @code{org-roam-buffer-visit-thing}
|
||||
@code{<RET>}: @code{org-roam-visit-thing}
|
||||
@end itemize
|
||||
|
||||
@code{org-roam-buffer-visit-thing} is a placeholder command, that is replaced by
|
||||
@code{org-roam-visit-thing} is a placeholder command, that is replaced by
|
||||
section-specific commands such as @code{org-roam-node-visit}.
|
||||
|
||||
@node Configuring what is displayed in the buffer
|
||||
@@ -821,10 +798,10 @@ There are currently 3 provided widget types:
|
||||
title/alias but are not linked
|
||||
@end itemize
|
||||
|
||||
To configure what sections are displayed in the buffer, set @code{org-roam-mode-section-functions}.
|
||||
To configure what sections are displayed in the buffer, set @code{org-roam-mode-sections}.
|
||||
|
||||
@lisp
|
||||
(setq org-roam-mode-section-functions
|
||||
(setq org-roam-mode-sections
|
||||
(list #'org-roam-backlinks-section
|
||||
#'org-roam-reflinks-section
|
||||
;; #'org-roam-unlinked-references-section
|
||||
@@ -864,14 +841,14 @@ For users that prefer using a side-window for the org-roam buffer, the following
|
||||
example configuration should provide a good starting point:
|
||||
|
||||
@lisp
|
||||
(add-to-list 'display-buffer-alist
|
||||
'("\\*org-roam\\*"
|
||||
(display-buffer-in-side-window)
|
||||
(side . right)
|
||||
(slot . 0)
|
||||
(window-width . 0.33)
|
||||
(window-parameters . ((no-other-window . t)
|
||||
(no-delete-other-windows . t)))))
|
||||
(add-to-list 'display-buffer-alist
|
||||
'("\\*org-roam\\*"
|
||||
(display-buffer-in-side-window)
|
||||
(side . right)
|
||||
(slot . 0)
|
||||
(window-width . 0.33)
|
||||
(window-parameters . ((no-other-window . t)
|
||||
(no-delete-other-windows . t)))))
|
||||
@end lisp
|
||||
|
||||
@node Styling the Org-roam buffer
|
||||
@@ -1253,7 +1230,7 @@ graph navigable.
|
||||
@node The roam-ref protocol
|
||||
@section The roam-ref protocol
|
||||
|
||||
This protocol finds or creates a new note with a given @code{ROAM_REFS}:
|
||||
This protocol finds or creates a new note with a given @code{roam_key}:
|
||||
|
||||
@image{images/roam-ref,,,,gif}
|
||||
|
||||
@@ -1277,7 +1254,8 @@ config.bind("<Ctrl-r>", "open javascript:location.href='org-protocol://roam-ref?
|
||||
@end example
|
||||
|
||||
where @code{template} is the template key for a template in
|
||||
@code{org-roam-capture-ref-templates} (see @ref{The Templating System}).
|
||||
@code{org-roam-capture-ref-templates} (see @ref{The Templating System}). These templates
|
||||
should contain a @code{#+roam_key: $@{ref@}} in it.
|
||||
|
||||
@node The Templating System
|
||||
@chapter The Templating System
|
||||
@@ -1369,27 +1347,7 @@ that is set before the capture process begins.
|
||||
|
||||
@item
|
||||
If none of the above applies, read a string using @code{completing-read}.
|
||||
@itemize
|
||||
@item
|
||||
Org-roam also provides the @code{$@{foo=default_val@}} syntax, where if a default
|
||||
value is provided, will be the initial value for the @code{foo} key during
|
||||
minibuffer completion.
|
||||
@end itemize
|
||||
@end itemize
|
||||
|
||||
One can check the list of available keys for nodes by inspecting the
|
||||
@code{org-roam-node} struct. At the time of writing, it is:
|
||||
|
||||
@lisp
|
||||
(cl-defstruct (org-roam-node (:constructor org-roam-node-create)
|
||||
(:copier nil))
|
||||
"A heading or top level file with an assigned ID property."
|
||||
file file-hash file-atime file-mtime
|
||||
id level point todo priority scheduled deadline title properties olp
|
||||
tags aliases refs)
|
||||
@end lisp
|
||||
|
||||
This makes @code{$@{file@}}, @code{$@{file-hash@}} etc. all valid substitutions.
|
||||
|
||||
@node Graphing
|
||||
@chapter Graphing
|
||||
@@ -1753,7 +1711,7 @@ documents (PDF, EPUB etc.) within Org-mode.
|
||||
|
||||
For example, though helm-bibtex provides the ability to visit notes for
|
||||
bibliographic entries, org-roam-bibtex extends it with the ability to visit the
|
||||
file with the right @code{ROAM_REFS}.
|
||||
file with the right @samp{#+ROAM_KEYS}.
|
||||
|
||||
@node Spaced Repetition
|
||||
@section Spaced Repetition
|
||||
@@ -1771,7 +1729,6 @@ Org-mode, and sync your cards to Anki via @uref{https://github.com/FooSoft/anki-
|
||||
* How do I have more than one Org-roam directory?::
|
||||
* How do I migrate from Roam Research?::
|
||||
* How do I create a note whose title already matches one of the candidates?::
|
||||
* How can I stop Org-roam from creating IDs everywhere?::
|
||||
@end menu
|
||||
|
||||
@node How do I have more than one Org-roam directory?
|
||||
@@ -1820,15 +1777,6 @@ set @code{ivy-use-selectable-prompt} to @code{t}, so that ``bar'' is now selecta
|
||||
the candidate list.
|
||||
@end itemize
|
||||
|
||||
@node How can I stop Org-roam from creating IDs everywhere?
|
||||
@section How can I stop Org-roam from creating IDs everywhere?
|
||||
|
||||
Other than the interactive commands that Org-roam provides, Org-roam does not
|
||||
create IDs everywhere. If you are noticing that IDs are being created even when
|
||||
you don't want them to be (e.g. when tangling an Org file), check the value you
|
||||
have set for @code{org-id-link-to-org-use-id}: setting it to @code{'create-if-interactive}
|
||||
is a popular option.
|
||||
|
||||
@node Migrating from Org-roam v1
|
||||
@chapter Migrating from Org-roam v1
|
||||
|
||||
@@ -1990,7 +1938,7 @@ INITIAL-INPUT is the initial minibuffer prompt value. FILTER-FN
|
||||
is a function to filter out nodes: it takes a single argument (an
|
||||
@code{org-roam-node}), and when nil is returned the node will be
|
||||
filtered out.
|
||||
SORT-FN is a function to sort nodes. See @code{org-roam-node-read-sort-by-file-mtime}
|
||||
SORT-FN is a function to sort nodes. See @code{org-roam-node-sort-by-file-mtime}
|
||||
for an example sort function.
|
||||
If REQUIRE-MATCH, the minibuffer prompt will require a match.
|
||||
@end defun
|
||||
@@ -2024,7 +1972,7 @@ instead. The exposed function to be used in extensions is @code{org-roam-capture
|
||||
|
||||
Main entry point.
|
||||
GOTO and KEYS correspond to `org-capture' arguments.
|
||||
INFO is a plist for filling up Org-roam's capture templates.
|
||||
INFO is an alist for filling up Org-roam's capture templates.
|
||||
NODE is an `org-roam-node' construct containing information about the node.
|
||||
PROPS is a plist containing additional Org-roam properties for each template.
|
||||
TEMPLATES is a list of org-roam templates.
|
||||
|
||||
@@ -1,192 +0,0 @@
|
||||
;;; org-roam-protocol.el --- Protocol handler for roam:// links -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
;; This program is free software; you can redistribute it and/or modify
|
||||
;; it under the terms of the GNU General Public License as published by
|
||||
;; the Free Software Foundation; either version 3, or (at your option)
|
||||
;; any later version.
|
||||
;;
|
||||
;; This program is distributed in the hope that it will be useful,
|
||||
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
;; GNU General Public License for more details.
|
||||
;;
|
||||
;; You should have received a copy of the GNU General Public License
|
||||
;; along with GNU Emacs; see the file COPYING. If not, write to the
|
||||
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
||||
;; Boston, MA 02110-1301, USA.
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This extension extends `org-protocol', adding custom Org-roam handlers to it
|
||||
;; to provide the next new protocols:
|
||||
;;
|
||||
;; 1. "roam-node": This protocol simply opens the node given by the node ID
|
||||
;; 2. "roam-ref": This protocol creates or opens the node with the given REF
|
||||
;;
|
||||
;; You can find detailed instructions on how to setup the protocol in the
|
||||
;; documentation for Org-roam.
|
||||
;;
|
||||
;;; Code:
|
||||
(require 'org-protocol)
|
||||
(require 'ol) ;; for org-link-decode
|
||||
(require 'org-roam)
|
||||
|
||||
;;; Options
|
||||
(defcustom org-roam-protocol-store-links nil
|
||||
"Whether to store links when capturing websites with `org-roam-protocol'."
|
||||
:type 'boolean
|
||||
:group 'org-roam)
|
||||
|
||||
(defcustom org-roam-capture-ref-templates
|
||||
'(("r" "ref" plain "%?"
|
||||
:if-new (file+head "${slug}.org"
|
||||
"#+title: ${title}")
|
||||
:unnarrowed t))
|
||||
"The Org-roam templates used during a capture from the roam-ref protocol.
|
||||
See `org-roam-capture-templates' for the template documentation."
|
||||
:group 'org-roam
|
||||
:type '(repeat
|
||||
(choice (list :tag "Multikey description"
|
||||
(string :tag "Keys ")
|
||||
(string :tag "Description"))
|
||||
(list :tag "Template entry"
|
||||
(string :tag "Keys ")
|
||||
(string :tag "Description ")
|
||||
(choice :tag "Capture Type " :value entry
|
||||
(const :tag "Org entry" entry)
|
||||
(const :tag "Plain list item" item)
|
||||
(const :tag "Checkbox item" checkitem)
|
||||
(const :tag "Plain text" plain)
|
||||
(const :tag "Table line" table-line))
|
||||
(choice :tag "Template "
|
||||
(string)
|
||||
(list :tag "File"
|
||||
(const :format "" file)
|
||||
(file :tag "Template file"))
|
||||
(list :tag "Function"
|
||||
(const :format "" function)
|
||||
(function :tag "Template function")))
|
||||
(plist :inline t
|
||||
;; Give the most common options as checkboxes
|
||||
:options (((const :format "%v " :if-new)
|
||||
(choice :tag "Node location"
|
||||
(list :tag "File"
|
||||
(const :format "" file)
|
||||
(string :tag " File"))
|
||||
(list :tag "File & Head Content"
|
||||
(const :format "" file+head)
|
||||
(string :tag " File")
|
||||
(string :tag " Head Content"))
|
||||
(list :tag "File & Outline path"
|
||||
(const :format "" file+olp)
|
||||
(string :tag " File")
|
||||
(list :tag "Outline path"
|
||||
(repeat (string :tag "Headline"))))
|
||||
(list :tag "File & Head Content & Outline path"
|
||||
(const :format "" file+head+olp)
|
||||
(string :tag " File")
|
||||
(string :tag " Head Content")
|
||||
(list :tag "Outline path"
|
||||
(repeat (string :tag "Headline"))))))
|
||||
((const :format "%v " :prepend) (const t))
|
||||
((const :format "%v " :immediate-finish) (const t))
|
||||
((const :format "%v " :jump-to-captured) (const t))
|
||||
((const :format "%v " :empty-lines) (const 1))
|
||||
((const :format "%v " :empty-lines-before) (const 1))
|
||||
((const :format "%v " :empty-lines-after) (const 1))
|
||||
((const :format "%v " :clock-in) (const t))
|
||||
((const :format "%v " :clock-keep) (const t))
|
||||
((const :format "%v " :clock-resume) (const t))
|
||||
((const :format "%v " :time-prompt) (const t))
|
||||
((const :format "%v " :tree-type) (const week))
|
||||
((const :format "%v " :unnarrowed) (const t))
|
||||
((const :format "%v " :table-line-pos) (string))
|
||||
((const :format "%v " :kill-buffer) (const t))))))))
|
||||
|
||||
;;; Handlers
|
||||
(defun org-roam-protocol-open-ref (info)
|
||||
"Process an org-protocol://roam-ref?ref= style url with INFO.
|
||||
|
||||
It opens or creates a note with the given ref.
|
||||
|
||||
javascript:location.href = \\='org-protocol://roam-ref?template=r&ref=\\='+ \\
|
||||
encodeURIComponent(location.href) + \\='&title=\\=' + \\
|
||||
encodeURIComponent(document.title) + \\='&body=\\=' + \\
|
||||
encodeURIComponent(window.getSelection())"
|
||||
(unless (plist-get info :ref)
|
||||
(user-error "No ref key provided"))
|
||||
(org-roam-plist-map! (lambda (k v)
|
||||
(org-link-decode
|
||||
(if (equal k :ref)
|
||||
(org-protocol-sanitize-uri v)
|
||||
v))) info)
|
||||
(when org-roam-protocol-store-links
|
||||
(push (list (plist-get info :ref)
|
||||
(plist-get info :title)) org-stored-links))
|
||||
(org-link-store-props :type (and (string-match org-link-plain-re
|
||||
(plist-get info :ref))
|
||||
(match-string 1 (plist-get info :ref)))
|
||||
:link (plist-get info :ref)
|
||||
:annotation (org-link-make-string (plist-get info :ref)
|
||||
(or (plist-get info :title)
|
||||
(plist-get info :ref)))
|
||||
:initial (or (plist-get info :body) ""))
|
||||
(raise-frame)
|
||||
(org-roam-capture-
|
||||
:keys (plist-get info :template)
|
||||
:node (org-roam-node-create :title (plist-get info :title))
|
||||
:info (list :ref (plist-get info :ref)
|
||||
:body (plist-get info :body))
|
||||
:templates org-roam-capture-ref-templates)
|
||||
nil)
|
||||
|
||||
(defun org-roam-protocol-open-node (info)
|
||||
"This handler simply opens the file with emacsclient.
|
||||
|
||||
INFO is a plist containing additional information passed by the protocol URL.
|
||||
It should contain the FILE key, pointing to the path of the file to open.
|
||||
|
||||
Example protocol string:
|
||||
|
||||
org-protocol://roam-node?node=uuid"
|
||||
(when-let ((node (plist-get info :node)))
|
||||
(raise-frame)
|
||||
(org-roam-node-visit (org-roam-populate (org-roam-node-create :id node)) nil 'force))
|
||||
nil)
|
||||
|
||||
(push '("org-roam-ref" :protocol "roam-ref" :function org-roam-protocol-open-ref)
|
||||
org-protocol-protocol-alist)
|
||||
(push '("org-roam-node" :protocol "roam-node" :function org-roam-protocol-open-node)
|
||||
org-protocol-protocol-alist)
|
||||
|
||||
;;; Capture implementation
|
||||
(add-hook 'org-roam-capture-preface-hook #'org-roam-protocol--try-capture-to-ref-h)
|
||||
(defun org-roam-protocol--try-capture-to-ref-h ()
|
||||
"Try to capture to an existing node that match the ref."
|
||||
(when-let ((node (and (plist-get org-roam-capture--info :ref)
|
||||
(org-roam-node-from-ref
|
||||
(plist-get org-roam-capture--info :ref)))))
|
||||
(set-buffer (org-capture-target-buffer (org-roam-node-file node)))
|
||||
(goto-char (org-roam-node-point node))
|
||||
(widen)
|
||||
(org-roam-node-id node)))
|
||||
|
||||
(add-hook 'org-roam-capture-new-node-hook #'org-roam-protocol--insert-captured-ref-h)
|
||||
(defun org-roam-protocol--insert-captured-ref-h ()
|
||||
"Insert the ref if any."
|
||||
(when-let ((ref (plist-get org-roam-capture--info :ref)))
|
||||
(org-roam-ref-add ref)))
|
||||
|
||||
|
||||
(provide 'org-roam-protocol)
|
||||
|
||||
;;; org-roam-protocol.el ends here
|
||||
@@ -1,11 +1,11 @@
|
||||
;;; org-roam-capture.el --- Capture functionality -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
@@ -27,17 +27,39 @@
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This module provides `org-capture' functionality for Org-roam. With this
|
||||
;; module the user can capture new nodes or capture new content to existing
|
||||
;; nodes.
|
||||
;;
|
||||
;; This library provides capture functionality for org-roam
|
||||
;;; Code:
|
||||
(require 'org-roam)
|
||||
;;;
|
||||
;;;; Library Requires
|
||||
(require 'org-capture)
|
||||
(eval-when-compile
|
||||
(require 'org-roam-macs)
|
||||
(require 'org-macs))
|
||||
(require 'org-roam-db)
|
||||
(require 'dash)
|
||||
(require 'cl-lib)
|
||||
|
||||
;;;; Declarations
|
||||
(defvar org-end-time-was-given)
|
||||
;; Declarations
|
||||
(declare-function org-roam-ref-add "org-roam" (ref))
|
||||
(declare-function org-datetree-find-date-create "org-datetree" (date &optional keep-restriction))
|
||||
(declare-function org-datetree-find-month-create "org-datetree" (d &optional keep-restriction))
|
||||
|
||||
(defvar org-roam-directory)
|
||||
|
||||
(defvar org-roam-capture--node nil
|
||||
"The node passed during an Org-roam capture.
|
||||
This variable is populated dynamically, and is only non-nil
|
||||
during the Org-roam capture process.")
|
||||
|
||||
(defvar org-roam-capture--info nil
|
||||
"A property-list of additional information passed to the Org-roam template.
|
||||
This variable is populated dynamically, and is only non-nil
|
||||
during the Org-roam capture process.")
|
||||
|
||||
(defconst org-roam-capture--template-keywords (list :if-new :id :link-description :call-location
|
||||
:region :override-default-time)
|
||||
"Keywords used in `org-roam-capture-templates' specific to Org-roam.")
|
||||
|
||||
;;; Options
|
||||
(defcustom org-roam-capture-templates
|
||||
'(("d" "default" plain "%?"
|
||||
:if-new (file+head "%<%Y%m%d%H%M%S>-${slug}.org"
|
||||
@@ -117,10 +139,6 @@ the following options:
|
||||
inserted at the start of the file. The datetree will be created,
|
||||
available options are day, week, month.
|
||||
|
||||
(node \"title or alias or ID of an existing node\")
|
||||
The point will be placed for an existing node, based on either, its
|
||||
title, alias or ID.
|
||||
|
||||
The rest of the entry is a property list of additional options. Recognized
|
||||
properties are:
|
||||
|
||||
@@ -324,104 +342,77 @@ streamlined user experience in Org-roam."
|
||||
((const :format "%v " :table-line-pos) (string))
|
||||
((const :format "%v " :kill-buffer) (const t))))))))
|
||||
|
||||
(defcustom org-roam-capture-new-node-hook nil
|
||||
(defvar org-roam-capture-new-node-hook (list #'org-roam-capture--insert-ref)
|
||||
"Normal-mode hooks run when a new Org-roam node is created.
|
||||
The current point is the point of the new node.
|
||||
The hooks must not move the point."
|
||||
The hooks must not move the point.")
|
||||
|
||||
(defcustom org-roam-capture-ref-templates
|
||||
'(("r" "ref" plain "%?"
|
||||
:if-new (file+head "${slug}.org"
|
||||
"#+title: ${title}")
|
||||
:unnarrowed t))
|
||||
"The Org-roam templates used during a capture from the roam-ref protocol.
|
||||
See `org-roam-capture-templates' for the template documentation."
|
||||
:group 'org-roam
|
||||
:type 'hook)
|
||||
:type '(repeat
|
||||
(choice (list :tag "Multikey description"
|
||||
(string :tag "Keys ")
|
||||
(string :tag "Description"))
|
||||
(list :tag "Template entry"
|
||||
(string :tag "Keys ")
|
||||
(string :tag "Description ")
|
||||
(choice :tag "Capture Type " :value entry
|
||||
(const :tag "Org entry" entry)
|
||||
(const :tag "Plain list item" item)
|
||||
(const :tag "Checkbox item" checkitem)
|
||||
(const :tag "Plain text" plain)
|
||||
(const :tag "Table line" table-line))
|
||||
(choice :tag "Template "
|
||||
(string)
|
||||
(list :tag "File"
|
||||
(const :format "" file)
|
||||
(file :tag "Template file"))
|
||||
(list :tag "Function"
|
||||
(const :format "" function)
|
||||
(function :tag "Template function")))
|
||||
(plist :inline t
|
||||
;; Give the most common options as checkboxes
|
||||
:options (((const :format "%v " :if-new)
|
||||
(choice :tag "Node location"
|
||||
(list :tag "File"
|
||||
(const :format "" file)
|
||||
(string :tag " File"))
|
||||
(list :tag "File & Head Content"
|
||||
(const :format "" file+head)
|
||||
(string :tag " File")
|
||||
(string :tag " Head Content"))
|
||||
(list :tag "File & Outline path"
|
||||
(const :format "" file+olp)
|
||||
(string :tag " File")
|
||||
(list :tag "Outline path"
|
||||
(repeat (string :tag "Headline"))))
|
||||
(list :tag "File & Head Content & Outline path"
|
||||
(const :format "" file+head+olp)
|
||||
(string :tag " File")
|
||||
(string :tag " Head Content")
|
||||
(list :tag "Outline path"
|
||||
(repeat (string :tag "Headline"))))))
|
||||
((const :format "%v " :prepend) (const t))
|
||||
((const :format "%v " :immediate-finish) (const t))
|
||||
((const :format "%v " :jump-to-captured) (const t))
|
||||
((const :format "%v " :empty-lines) (const 1))
|
||||
((const :format "%v " :empty-lines-before) (const 1))
|
||||
((const :format "%v " :empty-lines-after) (const 1))
|
||||
((const :format "%v " :clock-in) (const t))
|
||||
((const :format "%v " :clock-keep) (const t))
|
||||
((const :format "%v " :clock-resume) (const t))
|
||||
((const :format "%v " :time-prompt) (const t))
|
||||
((const :format "%v " :tree-type) (const week))
|
||||
((const :format "%v " :unnarrowed) (const t))
|
||||
((const :format "%v " :table-line-pos) (string))
|
||||
((const :format "%v " :kill-buffer) (const t))))))))
|
||||
|
||||
(defvar org-roam-capture-preface-hook nil
|
||||
"Hook run when Org-roam tries to determine capture location of the node.
|
||||
If any hook returns a value (which should be an ID), all hooks
|
||||
after it are ignored.
|
||||
|
||||
With this hook you can hijack controls over the location of the
|
||||
node for which the capture process is currently running for, or
|
||||
use to just perform an arbitrary side effect, e.g. modify the
|
||||
state related to the capture process. See `org-roam-protocol' and
|
||||
`org-roam-dailies' as examples for what and how this hook is used
|
||||
for.
|
||||
|
||||
If you're trying to perform the hijack, it's mandatory for you to:
|
||||
1. Set the currently active buffer for editing operations using
|
||||
`org-capture-target-buffer'.
|
||||
2. Place the point in this buffer from where the location starts
|
||||
from (e.g. if it's a file based node it should be the BOB,
|
||||
otherwise it should be the position from where the heading
|
||||
based node starts from).
|
||||
3. Return the ID (as a string) of the capturing node.
|
||||
|
||||
If you use this hook for any other purpose, but not the hijack,
|
||||
it's mandatory that you should return nil as the return value; so
|
||||
the capture process would be able to setup the capture buffer.
|
||||
|
||||
If you need to do something when you capture new nodes, use
|
||||
`org-roam-capture-new-node-hook' instead of this hook.
|
||||
|
||||
WARNING: This hook is primarily designed for the usage by the
|
||||
extensions and packages, and requires understanding of the
|
||||
internal capture process. If you don't understand it, you should
|
||||
learn these internals before using this or use it at your own
|
||||
risk breaking things.")
|
||||
|
||||
;;; Variables
|
||||
|
||||
(defvar org-roam-capture--node nil
|
||||
"The node passed during an Org-roam capture.
|
||||
This variable is populated dynamically, and is only non-nil
|
||||
during the Org-roam capture process.")
|
||||
|
||||
(defvar org-roam-capture--info nil
|
||||
"A property-list of additional information passed to the Org-roam template.
|
||||
This variable is populated dynamically, and is only non-nil
|
||||
during the Org-roam capture process.")
|
||||
|
||||
(defconst org-roam-capture--template-keywords (list :if-new :id :link-description :call-location
|
||||
:region)
|
||||
"Keywords used in `org-roam-capture-templates' specific to Org-roam.")
|
||||
|
||||
;;; Main entry point
|
||||
;;;###autoload
|
||||
(cl-defun org-roam-capture- (&key goto keys node info props templates)
|
||||
"Main entry point of `org-roam-capture' module.
|
||||
GOTO and KEYS correspond to `org-capture' arguments.
|
||||
INFO is a plist for filling up Org-roam's capture templates.
|
||||
NODE is an `org-roam-node' construct containing information about the node.
|
||||
PROPS is a plist containing additional Org-roam properties for each template.
|
||||
TEMPLATES is a list of org-roam templates."
|
||||
(let* ((props (plist-put props :call-location (point-marker)))
|
||||
(org-capture-templates
|
||||
(mapcar (lambda (template)
|
||||
(org-roam-capture--convert-template template props))
|
||||
(or templates org-roam-capture-templates)))
|
||||
(org-roam-capture--node node)
|
||||
(org-roam-capture--info info))
|
||||
(when (and (not keys)
|
||||
(= (length org-capture-templates) 1))
|
||||
(setq keys (caar org-capture-templates)))
|
||||
(org-capture goto keys)))
|
||||
|
||||
;;;###autoload
|
||||
(cl-defun org-roam-capture (&optional goto keys &key filter-fn templates info)
|
||||
"Launches an `org-capture' process for a new or existing node.
|
||||
This uses the templates defined at `org-roam-capture-templates'.
|
||||
Arguments GOTO and KEYS see `org-capture'.
|
||||
FILTER-FN is a function to filter out nodes: it takes an `org-roam-node',
|
||||
and when nil is returned the node will be filtered out.
|
||||
The TEMPLATES, if provided, override the list of capture templates (see
|
||||
`org-roam-capture-'.)
|
||||
The INFO, if provided, is passed along to the underlying `org-roam-capture-'."
|
||||
(interactive "P")
|
||||
(let ((node (org-roam-node-read nil filter-fn)))
|
||||
(org-roam-capture- :goto goto
|
||||
:info info
|
||||
:keys keys
|
||||
:templates templates
|
||||
:node node
|
||||
:props '(:immediate-finish nil))))
|
||||
|
||||
;;; Capture process
|
||||
(defun org-roam-capture-p ()
|
||||
"Return t if the current capture process is an Org-roam capture.
|
||||
This function is to only be called when `org-capture-plist' is
|
||||
@@ -441,44 +432,111 @@ the capture)."
|
||||
(setq org-capture-plist
|
||||
(plist-put org-capture-plist :org-roam p))))
|
||||
|
||||
;;;; Capture target
|
||||
(defun org-roam-capture--prepare-buffer ()
|
||||
"Prepare the capture buffer for the current Org-roam based capture template.
|
||||
This function will initialize and setup the capture buffer,
|
||||
create the target node (`:if-new') if it doesn't exist, and place
|
||||
the point for further processing by `org-capture'.
|
||||
;; FIXME: Pending upstream patch
|
||||
;; https://orgmode.org/list/87h7tv9pkm.fsf@hidden/T/#u
|
||||
;;
|
||||
;; Org-capture's behaviour right now is that `org-capture-plist' is valid only
|
||||
;; during the initialization of the Org-capture buffer. The value of
|
||||
;; `org-capture-plist' is saved into buffer-local `org-capture-current-plist'.
|
||||
;; However, the value for that particular capture is no longer accessible for
|
||||
;; hooks in `org-capture-after-finalize-hook', since the capture buffer has been
|
||||
;; cleaned up.
|
||||
;;
|
||||
;; This advice restores the global `org-capture-plist' during finalization, so
|
||||
;; the plist is valid during both initialization and finalization of the
|
||||
;; capture.
|
||||
(defun org-roam-capture--update-plist (&optional _)
|
||||
"Update global plist from local var."
|
||||
(setq org-capture-plist org-capture-current-plist))
|
||||
|
||||
Note: During the capture process this function is run by
|
||||
`org-capture-set-target-location', as a (function ...) based
|
||||
capture target."
|
||||
(let ((id (cond ((run-hook-with-args-until-success 'org-roam-capture-preface-hook))
|
||||
((and (org-roam-node-file org-roam-capture--node)
|
||||
(org-roam-node-point org-roam-capture--node))
|
||||
(set-buffer (org-capture-target-buffer (org-roam-node-file org-roam-capture--node)))
|
||||
(goto-char (org-roam-node-point org-roam-capture--node))
|
||||
(widen)
|
||||
(org-roam-node-id org-roam-capture--node))
|
||||
(t
|
||||
(org-roam-capture--setup-target-location)))))
|
||||
(org-roam-capture--adjust-point-for-capture-type)
|
||||
(org-capture-put :template
|
||||
(org-roam-capture--fill-template (org-capture-get :template)))
|
||||
(org-roam-capture--put :id id)
|
||||
(org-roam-capture--put :finalize (or (org-capture-get :finalize)
|
||||
(org-roam-capture--get :finalize)))))
|
||||
(advice-add 'org-capture-finalize :before #'org-roam-capture--update-plist)
|
||||
|
||||
(defun org-roam-capture--setup-target-location ()
|
||||
(defun org-roam-capture--finalize-find-file ()
|
||||
"Visit the buffer after Org-capture is done.
|
||||
This function is to be called in the Org-capture finalization process.
|
||||
ID is unused."
|
||||
(switch-to-buffer (org-capture-get :buffer)))
|
||||
|
||||
(defun org-roam-capture--finalize-insert-link ()
|
||||
"Insert a link to ID into the buffer where Org-capture was called.
|
||||
ID is the Org id of the newly captured content.
|
||||
This function is to be called in the Org-capture finalization process."
|
||||
(when-let* ((mkr (org-roam-capture--get :call-location))
|
||||
(buf (marker-buffer mkr)))
|
||||
(with-current-buffer buf
|
||||
(when-let ((region (org-roam-capture--get :region)))
|
||||
(org-roam-unshield-region (car region) (cdr region))
|
||||
(delete-region (car region) (cdr region))
|
||||
(set-marker (car region) nil)
|
||||
(set-marker (cdr region) nil))
|
||||
(org-with-point-at mkr
|
||||
(insert (org-link-make-string (concat "id:" (org-roam-capture--get :id))
|
||||
(org-roam-capture--get :link-description)))))))
|
||||
|
||||
(defun org-roam-capture--finalize ()
|
||||
"Finalize the `org-roam-capture' process."
|
||||
(when-let ((region (org-roam-capture--get :region)))
|
||||
(org-roam-unshield-region (car region) (cdr region)))
|
||||
(if org-note-abort
|
||||
(when-let ((new-file (org-roam-capture--get :new-file)))
|
||||
(org-roam-message "Deleting file for aborted capture %s" new-file)
|
||||
(when (find-buffer-visiting new-file)
|
||||
(kill-buffer (find-buffer-visiting new-file)))
|
||||
(delete-file new-file))
|
||||
(when-let* ((finalize (org-roam-capture--get :finalize))
|
||||
(org-roam-finalize-fn (intern (concat "org-roam-capture--finalize-"
|
||||
(symbol-name finalize)))))
|
||||
(if (functionp org-roam-finalize-fn)
|
||||
(funcall org-roam-finalize-fn)
|
||||
(funcall finalize))))
|
||||
(remove-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize))
|
||||
|
||||
(defun org-roam-capture--install-finalize ()
|
||||
"Install `org-roam-capture--finalize' if the capture is an Org-roam capture."
|
||||
(when (org-roam-capture-p)
|
||||
(add-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize)))
|
||||
|
||||
(add-hook 'org-capture-prepare-finalize-hook #'org-roam-capture--install-finalize)
|
||||
|
||||
(defun org-roam-capture--fill-template (template &optional org-capture-p)
|
||||
"Expand TEMPLATE and return it.
|
||||
It expands ${var} occurrences in TEMPLATE. When ORG-CAPTURE-P,
|
||||
also run Org-capture's template expansion."
|
||||
(funcall (if org-capture-p #'org-capture-fill-template #'identity)
|
||||
(org-roam-format
|
||||
template
|
||||
(lambda (key)
|
||||
(let ((fn (intern key))
|
||||
(node-fn (intern (concat "org-roam-node-" key)))
|
||||
(ksym (intern (concat ":" key))))
|
||||
(cond
|
||||
((fboundp fn)
|
||||
(funcall fn org-roam-capture--node))
|
||||
((fboundp node-fn)
|
||||
(funcall node-fn org-roam-capture--node))
|
||||
((plist-get org-roam-capture--info ksym)
|
||||
(plist-get org-roam-capture--info ksym))
|
||||
(t (let ((r (completing-read (format "%s: " key) nil)))
|
||||
(plist-put org-roam-capture--info ksym r)
|
||||
r))))))))
|
||||
|
||||
(defun org-roam-capture--insert-ref ()
|
||||
"Insert the ref if any."
|
||||
(when-let ((ref (plist-get org-roam-capture--info :ref)))
|
||||
(org-roam-ref-add ref)))
|
||||
|
||||
(defun org-roam-capture--goto-location ()
|
||||
"Initialize the buffer, and goto the location of the new capture.
|
||||
Return the ID of the location."
|
||||
(let (p new-file-p)
|
||||
(let (p)
|
||||
(pcase (or (org-roam-capture--get :if-new)
|
||||
(user-error "Template needs to specify `:if-new'"))
|
||||
(`(file ,path)
|
||||
(setq path (expand-file-name
|
||||
(string-trim (org-roam-capture--fill-template path t))
|
||||
org-roam-directory))
|
||||
(setq new-file-p (org-roam-capture--new-file-p path))
|
||||
(when new-file-p (org-roam-capture--put :new-file path))
|
||||
(unless (file-exists-p path)
|
||||
(org-roam-capture--put :new-file path))
|
||||
(set-buffer (org-capture-target-buffer path))
|
||||
(widen)
|
||||
(setq p (goto-char (point-min))))
|
||||
@@ -486,9 +544,9 @@ Return the ID of the location."
|
||||
(setq path (expand-file-name
|
||||
(string-trim (org-roam-capture--fill-template path t))
|
||||
org-roam-directory))
|
||||
(setq new-file-p (org-roam-capture--new-file-p path))
|
||||
(when new-file-p (org-roam-capture--put :new-file path))
|
||||
(set-buffer (org-capture-target-buffer path))
|
||||
(unless (file-exists-p path)
|
||||
(org-roam-capture--put :new-file path))
|
||||
(setq p (point-min))
|
||||
(let ((m (org-roam-capture-find-or-create-olp olp)))
|
||||
(goto-char m))
|
||||
@@ -497,9 +555,8 @@ Return the ID of the location."
|
||||
(setq path (expand-file-name
|
||||
(string-trim (org-roam-capture--fill-template path t))
|
||||
org-roam-directory))
|
||||
(setq new-file-p (org-roam-capture--new-file-p path))
|
||||
(set-buffer (org-capture-target-buffer path))
|
||||
(when new-file-p
|
||||
(unless (file-exists-p path)
|
||||
(org-roam-capture--put :new-file path)
|
||||
(insert (org-roam-capture--fill-template head t)))
|
||||
(widen)
|
||||
@@ -508,10 +565,9 @@ Return the ID of the location."
|
||||
(setq path (expand-file-name
|
||||
(string-trim (org-roam-capture--fill-template path t))
|
||||
org-roam-directory))
|
||||
(setq new-file-p (org-roam-capture--new-file-p path))
|
||||
(set-buffer (org-capture-target-buffer path))
|
||||
(widen)
|
||||
(when new-file-p
|
||||
(set-buffer (org-capture-target-buffer path))
|
||||
(unless (file-exists-p path)
|
||||
(org-roam-capture--put :new-file path)
|
||||
(insert (org-roam-capture--fill-template head t)))
|
||||
(setq p (point-min))
|
||||
@@ -566,25 +622,55 @@ Return the ID of the location."
|
||||
;; first try to get ID, then try to get title/alias
|
||||
(let ((node (or (org-roam-node-from-id title-or-id)
|
||||
(org-roam-node-from-title-or-alias title-or-id)
|
||||
(user-error "No node with title or id \"%s\"" title-or-id))))
|
||||
(user-error "No node with title or id \"%s\" title-or-id"))))
|
||||
(set-buffer (org-capture-target-buffer (org-roam-node-file node)))
|
||||
(goto-char (org-roam-node-point node))
|
||||
(setq p (org-roam-node-point node)))))
|
||||
;; Setup `org-id' for the current capture target and return it back to the
|
||||
;; caller.
|
||||
(save-excursion
|
||||
(goto-char p)
|
||||
(when-let* ((node org-roam-capture--node)
|
||||
(id (org-roam-node-id node)))
|
||||
(org-entry-put p "ID" id))
|
||||
(prog1
|
||||
(org-id-get-create)
|
||||
(run-hooks 'org-roam-capture-new-node-hook)))))
|
||||
(prog1
|
||||
;; Setup `org-id' for the current capture target and return it back to
|
||||
;; the caller.
|
||||
(save-excursion
|
||||
(goto-char p)
|
||||
(when-let* ((node org-roam-capture--node)
|
||||
(id (org-roam-node-id node)))
|
||||
(org-entry-put p "ID" id))
|
||||
(prog1
|
||||
(org-id-get-create)
|
||||
(run-hooks 'org-roam-capture-new-node-hook)))
|
||||
;; Adjust the point only after ID was generated and polluted to the
|
||||
;; current target in the capture buffer.
|
||||
(org-roam-capture--adjust-point-for-capture-type))))
|
||||
|
||||
(defun org-roam-capture--new-file-p (path)
|
||||
"Return t if PATH is for a new file with no visiting buffer."
|
||||
(not (or (file-exists-p path)
|
||||
(org-find-base-buffer-visiting path))))
|
||||
(defun org-roam-capture--adjust-point-for-capture-type (&optional pos)
|
||||
"Reposition the point for template insertion dependently on the capture type.
|
||||
Return the newly adjusted position of `point'.
|
||||
|
||||
POS is the current position of point (an integer) inside the
|
||||
currently active capture buffer, where the adjustment should
|
||||
start to begin from. If it's nil, then it will default to
|
||||
the current value of `point'."
|
||||
(or pos (setq pos (point)))
|
||||
(goto-char pos)
|
||||
(let ((location-type (if (= pos 1) 'beginning-of-file 'heading-at-point)))
|
||||
(and (eq location-type 'heading-at-point)
|
||||
(cl-assert (org-at-heading-p)))
|
||||
(pcase (org-capture-get :type)
|
||||
(`plain
|
||||
(cl-case location-type
|
||||
(beginning-of-file
|
||||
(if (org-capture-get :prepend)
|
||||
(let ((el (org-element-at-point)))
|
||||
(while (and (not (eobp))
|
||||
(memq (org-element-type el)
|
||||
'(drawer property-drawer keyword comment comment-block horizontal-rule)))
|
||||
(goto-char (org-element-property :end el))
|
||||
(setq el (org-element-at-point))))
|
||||
(goto-char (org-entry-end-position))))
|
||||
(heading-at-point
|
||||
(if (org-capture-get :prepend)
|
||||
(org-end-of-meta-data t)
|
||||
(goto-char (org-entry-end-position))))))))
|
||||
(point))
|
||||
|
||||
(defun org-roam-capture-find-or-create-olp (olp)
|
||||
"Return a marker pointing to the entry at OLP in the current buffer.
|
||||
@@ -632,106 +718,52 @@ you can catch it with `condition-case'."
|
||||
end (save-excursion (org-end-of-subtree t t))))
|
||||
(point-marker))))
|
||||
|
||||
(defun org-roam-capture--adjust-point-for-capture-type (&optional pos)
|
||||
"Reposition the point for template insertion dependently on the capture type.
|
||||
Return the newly adjusted position of `point'.
|
||||
(defun org-roam-capture--get-node-from-ref (ref)
|
||||
"Return the node from reference REF."
|
||||
(save-match-data
|
||||
(when (string-match org-link-plain-re ref)
|
||||
(let ((type (match-string 1 ref))
|
||||
(path (match-string 2 ref)))
|
||||
(when-let ((id (caar (org-roam-db-query
|
||||
[:select [nodes:id]
|
||||
:from refs
|
||||
:left-join nodes
|
||||
:on (= refs:node-id nodes:id)
|
||||
:where (= refs:type $s1)
|
||||
:and (= refs:ref $s2)
|
||||
:limit 1]
|
||||
type path))))
|
||||
(org-roam-populate (org-roam-node-create :id id)))))))
|
||||
|
||||
POS is the current position of point (an integer) inside the
|
||||
currently active capture buffer, where the adjustment should
|
||||
start to begin from. If it's nil, then it will default to
|
||||
the current value of `point'."
|
||||
(or pos (setq pos (point)))
|
||||
(goto-char pos)
|
||||
(let ((location-type (if (= pos 1) 'beginning-of-file 'heading-at-point)))
|
||||
(and (eq location-type 'heading-at-point)
|
||||
(cl-assert (org-at-heading-p)))
|
||||
(pcase (org-capture-get :type)
|
||||
(`plain
|
||||
(cl-case location-type
|
||||
(beginning-of-file
|
||||
(if (org-capture-get :prepend)
|
||||
(let ((el (org-element-at-point)))
|
||||
(while (and (not (eobp))
|
||||
(memq (org-element-type el)
|
||||
'(drawer property-drawer keyword comment comment-block horizontal-rule)))
|
||||
(goto-char (org-element-property :end el))
|
||||
(setq el (org-element-at-point))))
|
||||
(goto-char (org-entry-end-position))))
|
||||
(heading-at-point
|
||||
(if (org-capture-get :prepend)
|
||||
(org-end-of-meta-data t)
|
||||
(goto-char (org-entry-end-position))))))))
|
||||
(point))
|
||||
|
||||
;;;; Finalizers
|
||||
(add-hook 'org-capture-prepare-finalize-hook #'org-roam-capture--install-finalize-h)
|
||||
(defun org-roam-capture--install-finalize-h ()
|
||||
"Install `org-roam-capture--finalize' if the capture is an Org-roam capture."
|
||||
(when (org-roam-capture-p)
|
||||
(add-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize)))
|
||||
|
||||
(defun org-roam-capture--finalize ()
|
||||
"Finalize the `org-roam-capture' process."
|
||||
(when-let ((region (org-roam-capture--get :region)))
|
||||
(org-roam-unshield-region (car region) (cdr region)))
|
||||
(if org-note-abort
|
||||
(when-let ((new-file (org-roam-capture--get :new-file)))
|
||||
(org-roam-message "Deleting file for aborted capture %s" new-file)
|
||||
(when (find-buffer-visiting new-file)
|
||||
(kill-buffer (find-buffer-visiting new-file)))
|
||||
(delete-file new-file))
|
||||
(when-let* ((finalize (org-roam-capture--get :finalize))
|
||||
(org-roam-finalize-fn (intern (concat "org-roam-capture--finalize-"
|
||||
(symbol-name finalize)))))
|
||||
(if (functionp org-roam-finalize-fn)
|
||||
(funcall org-roam-finalize-fn)
|
||||
(funcall finalize))))
|
||||
(remove-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize))
|
||||
|
||||
(defun org-roam-capture--finalize-find-file ()
|
||||
"Visit the buffer after Org-capture is done.
|
||||
This function is to be called in the Org-capture finalization process.
|
||||
ID is unused."
|
||||
(switch-to-buffer (org-capture-get :buffer)))
|
||||
|
||||
(defun org-roam-capture--finalize-insert-link ()
|
||||
"Insert a link to ID into the buffer where Org-capture was called.
|
||||
ID is the Org id of the newly captured content.
|
||||
This function is to be called in the Org-capture finalization process."
|
||||
(when-let* ((mkr (org-roam-capture--get :call-location))
|
||||
(buf (marker-buffer mkr)))
|
||||
(with-current-buffer buf
|
||||
(when-let ((region (org-roam-capture--get :region)))
|
||||
(org-roam-unshield-region (car region) (cdr region))
|
||||
(delete-region (car region) (cdr region))
|
||||
(set-marker (car region) nil)
|
||||
(set-marker (cdr region) nil))
|
||||
(org-with-point-at mkr
|
||||
(insert (org-link-make-string (concat "id:" (org-roam-capture--get :id))
|
||||
(org-roam-capture--get :link-description)))))))
|
||||
|
||||
;;;; Processing of the capture templates
|
||||
(defun org-roam-capture--fill-template (template &optional org-capture-p)
|
||||
"Expand TEMPLATE and return it.
|
||||
It expands ${var} occurrences in TEMPLATE. When ORG-CAPTURE-P,
|
||||
also run Org-capture's template expansion."
|
||||
(funcall (if org-capture-p #'org-capture-fill-template #'identity)
|
||||
(org-roam-format-template
|
||||
template
|
||||
(lambda (key default-val)
|
||||
(let ((fn (intern key))
|
||||
(node-fn (intern (concat "org-roam-node-" key)))
|
||||
(ksym (intern (concat ":" key))))
|
||||
(cond
|
||||
((fboundp fn)
|
||||
(funcall fn org-roam-capture--node))
|
||||
((fboundp node-fn)
|
||||
(funcall node-fn org-roam-capture--node))
|
||||
((plist-get org-roam-capture--info ksym)
|
||||
(plist-get org-roam-capture--info ksym))
|
||||
(t (let ((r (completing-read (format "%s: " key) nil nil nil default-val)))
|
||||
(plist-put org-roam-capture--info ksym r)
|
||||
r))))))))
|
||||
(defun org-roam-capture--get-point ()
|
||||
"Return exact point to file for org-capture-template.
|
||||
This function is used solely in Org-roam's capture templates: see
|
||||
`org-roam-capture-templates'."
|
||||
(when (org-roam-capture--get :override-default-time)
|
||||
(org-capture-put :default-time (org-roam-capture--get :override-default-time)))
|
||||
(let ((id (cond ((plist-get org-roam-capture--info :ref)
|
||||
(if-let ((node (org-roam-capture--get-node-from-ref
|
||||
(plist-get org-roam-capture--info :ref))))
|
||||
(progn
|
||||
(set-buffer (org-capture-target-buffer (org-roam-node-file node)))
|
||||
(goto-char (org-roam-node-point node))
|
||||
(widen)
|
||||
(org-end-of-subtree t t))
|
||||
(org-roam-capture--goto-location)))
|
||||
((and (org-roam-node-file org-roam-capture--node)
|
||||
(org-roam-node-point org-roam-capture--node))
|
||||
(set-buffer (org-capture-target-buffer (org-roam-node-file org-roam-capture--node)))
|
||||
(goto-char (org-roam-node-point org-roam-capture--node))
|
||||
(widen)
|
||||
(org-end-of-subtree t t)
|
||||
(org-roam-node-id org-roam-capture--node))
|
||||
(t
|
||||
(org-roam-capture--goto-location)))))
|
||||
(org-capture-put :template
|
||||
(org-roam-capture--fill-template (org-capture-get :template)))
|
||||
(org-roam-capture--put :id id)
|
||||
(org-roam-capture--put :finalize (or (org-capture-get :finalize)
|
||||
(org-roam-capture--get :finalize)))))
|
||||
|
||||
(defun org-roam-capture--convert-template (template &optional props)
|
||||
"Convert TEMPLATE from Org-roam syntax to `org-capture-templates' syntax.
|
||||
@@ -740,9 +772,7 @@ properties to be added to the template."
|
||||
(pcase template
|
||||
(`(,_key ,_desc)
|
||||
template)
|
||||
((or `(,key ,desc ,type ignore ,body . ,rest)
|
||||
`(,key ,desc ,type (function ignore) ,body . ,rest)
|
||||
`(,key ,desc ,type ,body . ,rest))
|
||||
(`(,key ,desc ,type ,body . ,rest)
|
||||
(setq rest (append rest props))
|
||||
(let (org-roam-plist options)
|
||||
(while rest
|
||||
@@ -755,12 +785,43 @@ properties to be added to the template."
|
||||
(if custom
|
||||
(setq org-roam-plist (plist-put org-roam-plist key val))
|
||||
(setq options (plist-put options key val)))))
|
||||
(append `(,key ,desc ,type #'org-roam-capture--prepare-buffer ,body)
|
||||
(append `(,key ,desc ,type #'org-roam-capture--get-point ,body)
|
||||
options
|
||||
(list :org-roam org-roam-plist))))
|
||||
(_
|
||||
(signal 'invalid-template template))))
|
||||
|
||||
;;;###autoload
|
||||
(cl-defun org-roam-capture- (&key goto keys node info props templates)
|
||||
"Main entry point.
|
||||
GOTO and KEYS correspond to `org-capture' arguments.
|
||||
INFO is an alist for filling up Org-roam's capture templates.
|
||||
NODE is an `org-roam-node' construct containing information about the node.
|
||||
PROPS is a plist containing additional Org-roam properties for each template.
|
||||
TEMPLATES is a list of org-roam templates."
|
||||
(let* ((props (plist-put props :call-location (point-marker)))
|
||||
(org-capture-templates
|
||||
(mapcar (lambda (template)
|
||||
(org-roam-capture--convert-template template props))
|
||||
(or templates org-roam-capture-templates)))
|
||||
(org-roam-capture--node node)
|
||||
(org-roam-capture--info info))
|
||||
(when (and (not keys)
|
||||
(= (length org-capture-templates) 1))
|
||||
(setq keys (caar org-capture-templates)))
|
||||
(org-capture goto keys)))
|
||||
|
||||
;;;###autoload
|
||||
(defun org-roam-capture (&optional goto keys)
|
||||
"Launches an `org-capture' process for a new or existing note.
|
||||
This uses the templates defined at `org-roam-capture-templates'.
|
||||
Arguments GOTO and KEYS see `org-capture'."
|
||||
(interactive "P")
|
||||
(let ((node (org-roam-node-read)))
|
||||
(org-roam-capture- :goto goto
|
||||
:keys keys
|
||||
:node node
|
||||
:props '(:immediate-finish nil))))
|
||||
|
||||
(provide 'org-roam-capture)
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
;;; org-roam-compat.el --- Backward compatibility code -*- coding: utf-8; lexical-binding: t; -*-
|
||||
;;; org-roam-compat.el --- Compatibility Code -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Package-Requires: ((emacs "26.1"))
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
@@ -27,10 +27,12 @@
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This file is dedicated to maintain backward compatibility with older older
|
||||
;; Emacsen and Org-roam versions.
|
||||
;; This file contains code needed for backward compatibility with older Emacsen
|
||||
;; and previous versions of org-roam.
|
||||
;;
|
||||
;;; Code:
|
||||
;;;; Library Requires
|
||||
|
||||
;;; Backports
|
||||
;; REVIEW Remove when 26.x support is dropped. This is exact the same as
|
||||
;; `directory-files-recursively' from Emacs 26, but with FOLLOW-SYMLINKS
|
||||
@@ -95,91 +97,7 @@ recursion."
|
||||
(push (concat dir "/" file) files)))))
|
||||
(nconc result (nreverse files))))
|
||||
|
||||
;;; Compatibility hacks and patches
|
||||
(advice-add #'org-id-add-location :around #'org-roam--handle-absent-org-id-locations-file-a)
|
||||
(defun org-roam--handle-absent-org-id-locations-file-a (fn &rest args)
|
||||
"Gracefully handle errors related to absence of `org-id-locations-file'.
|
||||
FN is `org-id-locations-file' that comes from advice and ARGS are
|
||||
passed to it."
|
||||
(let (result)
|
||||
;; Use `unwind-protect' over `condition-case' because `org-id' can produce various other errors, but all
|
||||
;; of its errors are generic ones, so trapping all of them isn't a good idea and preserving the correct
|
||||
;; backtrace is valuable.
|
||||
(unwind-protect (setq result (apply fn args))
|
||||
(unless result
|
||||
(unless org-id-locations
|
||||
;; Pre-allocate the hash table to avoid weird access related errors during the regeneration.
|
||||
(setq org-id-locations (make-hash-table :type 'equal)))
|
||||
;; `org-id' makes the assumption that `org-id-locations-file' will be stored in `user-emacs-directory'
|
||||
;; which always exist if you have Emacs, so it uses `with-temp-file' to write to the file. However,
|
||||
;; the users *do* change the path to this file and `with-temp-file' unable to create the file, if the
|
||||
;; path to it consists of directories that don't exist. We'll have to handle this ourselves.
|
||||
(unless (file-exists-p (file-truename org-id-locations-file))
|
||||
;; If permissions allow that, try to create the user specified directory path to
|
||||
;; `org-id-locations-file' ourselves.
|
||||
(condition-case _err
|
||||
(progn (org-roam-message (concat "`org-id-locations-file' (%s) doesn't exist. "
|
||||
"Trying to regenerate it (this may take a while)...")
|
||||
org-id-locations-file)
|
||||
(make-directory (file-name-directory (file-truename org-id-locations-file)))
|
||||
(org-roam-update-org-id-locations)
|
||||
(apply fn args))
|
||||
;; In case of failure (lack of permissions), we'll patch it to at least handle the current session
|
||||
;; without errors.
|
||||
(file-error (org-roam-message "Failed to regenerate `org-id-locations-file'")
|
||||
(lwarn 'org-roam :error "
|
||||
--------
|
||||
WARNING: `org-id-locations-file' (%s) doesn't exist!
|
||||
Org-roam is unable to create it for you.
|
||||
--------
|
||||
|
||||
This happens when Emacs doesn't have permissions to create the
|
||||
path to your `org-id-locations-file'. Org-roam will now fallback
|
||||
storing the file in your current `org-roam-directory', but the
|
||||
warning will keep popup with each new session.
|
||||
|
||||
To stop this warning from popping up, set `org-id-locations-file'
|
||||
to the location you want and ensure that the path exists on your
|
||||
filesystem, then run M-x `org-roam-update-org-id-locations'.
|
||||
|
||||
Note: While Org-roam doesn't depend on `org-id-locations-file' to
|
||||
lookup IDs for the nodes that are stored in the database, it
|
||||
still tries to keep it updated so IDs work across other files in
|
||||
Org-mode, so the IDs used in your `org-roam-directory' would be
|
||||
able to cross-reference outside of `org-roam-directory'. It also
|
||||
allows to keep linking with \"id:\" links within the current
|
||||
`org-roam-directory' to headings and files that are excluded from
|
||||
identification (e.g. with \"ROAM_EXCLUDE\" property) as Org-roam
|
||||
nodes." org-id-locations-file)
|
||||
(setq org-id-locations-file
|
||||
(expand-file-name ".orgids" (file-truename org-roam-directory)))
|
||||
(apply fn args)))))
|
||||
result)))
|
||||
|
||||
;;; Obsolete aliases (remove after next major release)
|
||||
(define-obsolete-function-alias
|
||||
'org-roam-setup
|
||||
'org-roam-db-autosync-enable "org-roam 2.0")
|
||||
(define-obsolete-function-alias
|
||||
'org-roam-teardown
|
||||
'org-roam-db-autosync-disable "org-roam 2.0")
|
||||
|
||||
(define-obsolete-variable-alias
|
||||
'org-roam-current-node
|
||||
'org-roam-buffer-current-node "org-roam 2.0")
|
||||
(define-obsolete-variable-alias
|
||||
'org-roam-current-directory
|
||||
'org-roam-buffer-current-directory "org-roam 2.0")
|
||||
(define-obsolete-function-alias
|
||||
'org-roam-buffer-render
|
||||
'org-roam-buffer-render-contents "org-roam 2.0")
|
||||
(define-obsolete-function-alias
|
||||
'org-roam-buffer
|
||||
'org-roam-buffer-display-dedicated "org-roam 2.0")
|
||||
(define-obsolete-function-alias
|
||||
'org-roam-visit-thing
|
||||
'org-roam-buffer-visit-thing "org-roam 2.0")
|
||||
|
||||
(define-obsolete-function-alias
|
||||
'org-roam-dailies-find-today
|
||||
'org-roam-dailies-goto-today "org-roam 2.0")
|
||||
@@ -200,7 +118,6 @@ nodes." org-id-locations-file)
|
||||
'org-roam-dailies-goto-date "org-roam 2.0")
|
||||
|
||||
;;; Obsolete functions
|
||||
(make-obsolete 'org-roam-get-keyword 'org-collect-keywords "org-roam 2.0")
|
||||
|
||||
(provide 'org-roam-compat)
|
||||
|
||||
|
||||
107
org-roam-completion.el
Normal file
107
org-roam-completion.el
Normal file
@@ -0,0 +1,107 @@
|
||||
;;; org-roam-completion.el --- Completion features -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
;; This program is free software; you can redistribute it and/or modify
|
||||
;; it under the terms of the GNU General Public License as published by
|
||||
;; the Free Software Foundation; either version 3, or (at your option)
|
||||
;; any later version.
|
||||
;;
|
||||
;; This program is distributed in the hope that it will be useful,
|
||||
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
;; GNU General Public License for more details.
|
||||
;;
|
||||
;; You should have received a copy of the GNU General Public License
|
||||
;; along with GNU Emacs; see the file COPYING. If not, write to the
|
||||
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
||||
;; Boston, MA 02110-1301, USA.
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This library provides completion-at-point functions for Org-roam.
|
||||
;;
|
||||
;; The two main functions provided to capf are:
|
||||
;;
|
||||
;; `org-roam-complete-link-at-point' provides completions to nodes
|
||||
;; within link brackets
|
||||
;;
|
||||
;; `org-roam-complete-everywhere' provides completions for nodes everywhere,
|
||||
;; matching the symbol at point
|
||||
;;
|
||||
;;; Code:
|
||||
(require 'cl-lib)
|
||||
(require 'org-element)
|
||||
|
||||
(declare-function org-roam--get-titles "org-roam")
|
||||
|
||||
(defcustom org-roam-completion-everywhere nil
|
||||
"When non-nil, provide link completion matching outside of Org links."
|
||||
:group 'org-roam
|
||||
:type 'boolean)
|
||||
|
||||
(defvar org-roam-completion-functions (list #'org-roam-complete-link-at-point
|
||||
#'org-roam-complete-everywhere)
|
||||
"List of functions to be used with `completion-at-point' for Org-roam.")
|
||||
|
||||
(defconst org-roam-bracket-completion-re
|
||||
"\\[\\[\\(\\(?:roam:\\)?\\)\\([^z-a]*\\)]]"
|
||||
"Regex for completion within link brackets.
|
||||
We use this as a substitute for `org-link-bracket-re', because
|
||||
`org-link-bracket-re' requires content within the brackets for a match.")
|
||||
|
||||
(defun org-roam-complete-everywhere ()
|
||||
"Provides completions for links for any word at point.
|
||||
This is a `completion-at-point' function, and is active when
|
||||
`org-roam-completion-everywhere' is non-nil."
|
||||
(when (and org-roam-completion-everywhere
|
||||
(thing-at-point 'word)
|
||||
(not (save-match-data (org-in-regexp org-link-any-re))))
|
||||
(let ((bounds (bounds-of-thing-at-point 'word)))
|
||||
(list (car bounds) (cdr bounds)
|
||||
(completion-table-dynamic
|
||||
(lambda (_)
|
||||
(funcall #'org-roam--get-titles)))
|
||||
:exit-function
|
||||
(lambda (str _status)
|
||||
(delete-char (- (length str)))
|
||||
(insert "[[roam:" str "]]"))))))
|
||||
|
||||
(defun org-roam-complete-link-at-point ()
|
||||
"Do appropriate completion for the link at point."
|
||||
(let (roam-p start end)
|
||||
(when (org-in-regexp org-roam-bracket-completion-re 1)
|
||||
(setq roam-p (not (string-blank-p (match-string 1)))
|
||||
start (match-beginning 2)
|
||||
end (match-end 2))
|
||||
(list start end
|
||||
(completion-table-dynamic
|
||||
(lambda (_)
|
||||
(funcall #'org-roam--get-titles)))
|
||||
:exit-function
|
||||
(lambda (str &rest _)
|
||||
(delete-char (- 0 (length str)))
|
||||
(insert (concat (unless roam-p "roam:")
|
||||
str))
|
||||
(forward-char 2))))))
|
||||
|
||||
(defun org-roam-complete-at-point ()
|
||||
"."
|
||||
(run-hook-with-args-until-success 'org-roam-completion-functions))
|
||||
|
||||
(defun org-roam--register-completion-functions ()
|
||||
"."
|
||||
(add-hook 'completion-at-point-functions #'org-roam-complete-at-point nil t))
|
||||
|
||||
(add-hook 'org-roam-find-file-hook #'org-roam--register-completion-functions)
|
||||
|
||||
(provide 'org-roam-completion)
|
||||
|
||||
;;; org-roam-completion.el ends here
|
||||
@@ -1,14 +1,14 @@
|
||||
;;; org-roam-dailies.el --- Daily-notes for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
|
||||
;;;
|
||||
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; Copyright © 2020 Leo Vivier <leo.vivier+dev@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; Leo Vivier <leo.vivier+dev@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org-roam "2.1"))
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
@@ -29,25 +29,27 @@
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This extension provides functionality for creating daily-notes, or shortly
|
||||
;; "dailies". Dailies implemented here as a unique node per unique file, where
|
||||
;; each file named after certain date and stored in `org-roam-dailies-directory'.
|
||||
;;
|
||||
;; One can use dailies for various purposes, e.g. journaling, fleeting notes,
|
||||
;; scratch notes and whatever else you can came up with.
|
||||
;; This library provides functionality for creating daily-notes. This is a
|
||||
;; concept borrowed from Roam Research.
|
||||
;;
|
||||
;;; Code:
|
||||
;;; Library Requires
|
||||
(require 'org-capture)
|
||||
(require 'org-roam-capture)
|
||||
(require 'f)
|
||||
(require 'dash)
|
||||
(require 'org-roam)
|
||||
|
||||
;;; Faces
|
||||
;;;; Declarations
|
||||
(defvar org-roam-directory)
|
||||
(defvar org-roam-file-extensions)
|
||||
(declare-function org-roam-file-p "org-roam")
|
||||
|
||||
;;;; Faces
|
||||
(defface org-roam-dailies-calendar-note
|
||||
'((t :inherit (org-link) :underline nil))
|
||||
"Face for dates with a daily-note in the calendar."
|
||||
:group 'org-roam-faces)
|
||||
|
||||
;;; Options
|
||||
;;;; Customizable variables
|
||||
(defcustom org-roam-dailies-directory "daily/"
|
||||
"Path to daily-notes.
|
||||
This path is relative to `org-roam-directory'."
|
||||
@@ -65,8 +67,6 @@ This path is relative to `org-roam-directory'."
|
||||
:if-new (file+head "%<%Y-%m-%d>.org"
|
||||
"#+title: %<%Y-%m-%d>\n")))
|
||||
"Capture templates for daily-notes in Org-roam.
|
||||
Note that for daily files to show up in the calendar, they have to be of format
|
||||
\"org-time-string.org\".
|
||||
See `org-roam-capture-templates' for the template documentation."
|
||||
:group 'org-roam
|
||||
:type '(repeat
|
||||
@@ -127,8 +127,37 @@ See `org-roam-capture-templates' for the template documentation."
|
||||
((const :format "%v " :table-line-pos) (string))
|
||||
((const :format "%v " :kill-buffer) (const t))))))))
|
||||
|
||||
;;; Commands
|
||||
;;;; Today
|
||||
;;;###autoload
|
||||
(defun org-roam-dailies-find-directory ()
|
||||
"Find and open `org-roam-dailies-directory'."
|
||||
(interactive)
|
||||
(find-file (expand-file-name org-roam-dailies-directory org-roam-directory)))
|
||||
|
||||
(defun org-roam-dailies--daily-note-p (&optional file)
|
||||
"Return t if FILE is an Org-roam daily-note, nil otherwise.
|
||||
If FILE is not specified, use the current buffer's file-path."
|
||||
(when-let ((path (expand-file-name
|
||||
(or file
|
||||
(buffer-file-name (buffer-base-buffer)))))
|
||||
(directory (expand-file-name org-roam-dailies-directory org-roam-directory)))
|
||||
(setq path (expand-file-name path))
|
||||
(save-match-data
|
||||
(and
|
||||
(org-roam-file-p path)
|
||||
(f-descendant-of-p path directory)))))
|
||||
|
||||
(defun org-roam-dailies--capture (time &optional goto)
|
||||
"Capture an entry in a daily-note for TIME, creating it if necessary.
|
||||
When GOTO is non-nil, go the note without creating an entry."
|
||||
(let ((org-roam-directory (expand-file-name org-roam-dailies-directory org-roam-directory)))
|
||||
(org-roam-capture- :goto (when goto '(4))
|
||||
:node (org-roam-node-create)
|
||||
:templates org-roam-dailies-capture-templates
|
||||
:props (list :override-default-time time)))
|
||||
(when goto (run-hooks 'org-roam-dailies-find-file-hook)))
|
||||
|
||||
;;;; Commands
|
||||
;;; Today
|
||||
;;;###autoload
|
||||
(defun org-roam-dailies-capture-today (&optional goto)
|
||||
"Create an entry in the daily-note for today.
|
||||
@@ -142,7 +171,7 @@ When GOTO is non-nil, go the note without creating an entry."
|
||||
(interactive)
|
||||
(org-roam-dailies-capture-today t))
|
||||
|
||||
;;;; Tomorrow
|
||||
;;; Tomorrow
|
||||
;;;###autoload
|
||||
(defun org-roam-dailies-capture-tomorrow (n &optional goto)
|
||||
"Create an entry in the daily-note for tomorrow.
|
||||
@@ -163,7 +192,7 @@ future."
|
||||
(interactive "p")
|
||||
(org-roam-dailies-capture-tomorrow n t))
|
||||
|
||||
;;;; Yesterday
|
||||
;;; Yesterday
|
||||
;;;###autoload
|
||||
(defun org-roam-dailies-capture-yesterday (n &optional goto)
|
||||
"Create an entry in the daily-note for yesteday.
|
||||
@@ -183,7 +212,31 @@ future."
|
||||
(interactive "p")
|
||||
(org-roam-dailies-capture-tomorrow (- n) t))
|
||||
|
||||
;;;; Date
|
||||
;;; Calendar
|
||||
(defun org-roam-dailies-calendar--file-to-date (&optional file)
|
||||
"Convert FILE to date.
|
||||
Return (MONTH DAY YEAR)."
|
||||
(let ((file (or file
|
||||
(buffer-base-buffer (buffer-file-name)))))
|
||||
(cl-destructuring-bind (_ _ _ d m y _ _ _)
|
||||
(org-parse-time-string
|
||||
(file-name-sans-extension
|
||||
(file-name-nondirectory file)))
|
||||
(list m d y))))
|
||||
|
||||
(defun org-roam-dailies-calendar--date-to-time (date)
|
||||
"Convert DATE as returned from then calendar (MONTH DAY YEAR) to a time."
|
||||
(encode-time 0 0 0 (nth 1 date) (nth 0 date) (nth 2 date)))
|
||||
|
||||
(defun org-roam-dailies-calendar-mark-entries ()
|
||||
"Mark days in the calendar for which a daily-note is present."
|
||||
(when (file-exists-p (expand-file-name org-roam-dailies-directory org-roam-directory))
|
||||
(dolist (date (mapcar #'org-roam-dailies-calendar--file-to-date
|
||||
(org-roam-dailies--list-files)))
|
||||
(when (calendar-date-is-visible-p date)
|
||||
(calendar-mark-visible-date date 'org-roam-dailies-calendar-note)))))
|
||||
|
||||
;;; Date
|
||||
;;;###autoload
|
||||
(defun org-roam-dailies-capture-date (&optional goto prefer-future)
|
||||
"Create an entry in the daily-note for a date using the calendar.
|
||||
@@ -204,7 +257,20 @@ Prefer past dates, unless PREFER-FUTURE is non-nil."
|
||||
(interactive)
|
||||
(org-roam-dailies-capture-date t prefer-future))
|
||||
|
||||
;;;; Navigation
|
||||
;;; Navigation
|
||||
(defun org-roam-dailies--list-files (&rest extra-files)
|
||||
"List all files in `org-roam-dailies-directory'.
|
||||
EXTRA-FILES can be used to append extra files to the list."
|
||||
(let ((dir (expand-file-name org-roam-dailies-directory org-roam-directory))
|
||||
(regexp (rx-to-string `(and "." (or ,@org-roam-file-extensions)))))
|
||||
(append (--remove (let ((file (file-name-nondirectory it)))
|
||||
(when (or (auto-save-file-name-p file)
|
||||
(backup-file-name-p file)
|
||||
(string-match "^\\." file))
|
||||
it))
|
||||
(directory-files-recursively dir regexp))
|
||||
extra-files)))
|
||||
|
||||
(defun org-roam-dailies-goto-next-note (&optional n)
|
||||
"Find next daily-note.
|
||||
|
||||
@@ -242,82 +308,10 @@ negative, find note N days in the future."
|
||||
(let ((n (if n (- n) -1)))
|
||||
(org-roam-dailies-goto-next-note n)))
|
||||
|
||||
(defun org-roam-dailies--list-files (&rest extra-files)
|
||||
"List all files in `org-roam-dailies-directory'.
|
||||
EXTRA-FILES can be used to append extra files to the list."
|
||||
(let ((dir (expand-file-name org-roam-dailies-directory org-roam-directory))
|
||||
(regexp (rx-to-string `(and "." (or ,@org-roam-file-extensions)))))
|
||||
(append (--remove (let ((file (file-name-nondirectory it)))
|
||||
(when (or (auto-save-file-name-p file)
|
||||
(backup-file-name-p file)
|
||||
(string-match "^\\." file))
|
||||
it))
|
||||
(directory-files-recursively dir regexp))
|
||||
extra-files)))
|
||||
|
||||
(defun org-roam-dailies--daily-note-p (&optional file)
|
||||
"Return t if FILE is an Org-roam daily-note, nil otherwise.
|
||||
If FILE is not specified, use the current buffer's file-path."
|
||||
(when-let ((path (expand-file-name
|
||||
(or file
|
||||
(buffer-file-name (buffer-base-buffer)))))
|
||||
(directory (expand-file-name org-roam-dailies-directory org-roam-directory)))
|
||||
(setq path (expand-file-name path))
|
||||
(save-match-data
|
||||
(and
|
||||
(org-roam-file-p path)
|
||||
(f-descendant-of-p path directory)))))
|
||||
|
||||
;;;###autoload
|
||||
(defun org-roam-dailies-find-directory ()
|
||||
"Find and open `org-roam-dailies-directory'."
|
||||
(interactive)
|
||||
(find-file (expand-file-name org-roam-dailies-directory org-roam-directory)))
|
||||
|
||||
;;; Calendar integration
|
||||
(defun org-roam-dailies-calendar--file-to-date (file)
|
||||
"Convert FILE to date.
|
||||
Return (MONTH DAY YEAR) or nil if not an Org time-string."
|
||||
(ignore-errors
|
||||
(cl-destructuring-bind (_ _ _ d m y _ _ _)
|
||||
(org-parse-time-string
|
||||
(file-name-sans-extension
|
||||
(file-name-nondirectory file)))
|
||||
(list m d y))))
|
||||
|
||||
(defun org-roam-dailies-calendar-mark-entries ()
|
||||
"Mark days in the calendar for which a daily-note is present."
|
||||
(when (file-exists-p (expand-file-name org-roam-dailies-directory org-roam-directory))
|
||||
(dolist (date (remove nil
|
||||
(mapcar #'org-roam-dailies-calendar--file-to-date
|
||||
(org-roam-dailies--list-files))))
|
||||
(when (calendar-date-is-visible-p date)
|
||||
(calendar-mark-visible-date date 'org-roam-dailies-calendar-note)))))
|
||||
|
||||
(add-hook 'calendar-today-visible-hook #'org-roam-dailies-calendar-mark-entries)
|
||||
(add-hook 'calendar-today-invisible-hook #'org-roam-dailies-calendar-mark-entries)
|
||||
|
||||
;;; Capture implementation
|
||||
(add-to-list 'org-roam-capture--template-keywords :override-default-time)
|
||||
|
||||
(defun org-roam-dailies--capture (time &optional goto)
|
||||
"Capture an entry in a daily-note for TIME, creating it if necessary.
|
||||
When GOTO is non-nil, go the note without creating an entry."
|
||||
(let ((org-roam-directory (expand-file-name org-roam-dailies-directory org-roam-directory)))
|
||||
(org-roam-capture- :goto (when goto '(4))
|
||||
:node (org-roam-node-create)
|
||||
:templates org-roam-dailies-capture-templates
|
||||
:props (list :override-default-time time)))
|
||||
(when goto (run-hooks 'org-roam-dailies-find-file-hook)))
|
||||
|
||||
(add-hook 'org-roam-capture-preface-hook #'org-roam-dailies--override-capture-time-h)
|
||||
(defun org-roam-dailies--override-capture-time-h ()
|
||||
"Override the `:default-time' with the time from `:override-default-time'."
|
||||
(prog1 nil
|
||||
(when (org-roam-capture--get :override-default-time)
|
||||
(org-capture-put :default-time (org-roam-capture--get :override-default-time)))))
|
||||
|
||||
;;; Bindings
|
||||
;;;; Bindings
|
||||
(defvar org-roam-dailies-map (make-sparse-keymap)
|
||||
"Keymap for `org-roam-dailies'.")
|
||||
|
||||
267
org-roam-db.el
267
org-roam-db.el
@@ -1,11 +1,11 @@
|
||||
;;; org-roam-db.el --- Org-roam database API -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
@@ -27,15 +27,36 @@
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This module provides the underlying database API to Org-roam.
|
||||
;; This library provides the underlying database api to org-roam.
|
||||
;;
|
||||
;;; Code:
|
||||
(require 'org-roam)
|
||||
(defvar org-outline-path-cache)
|
||||
;;;; Library Requires
|
||||
(eval-when-compile (require 'subr-x))
|
||||
(require 'emacsql)
|
||||
(require 'emacsql-sqlite)
|
||||
(require 'seq)
|
||||
|
||||
;;; Options
|
||||
(eval-and-compile
|
||||
(require 'org-roam-macs)
|
||||
;; For `org-with-wide-buffer'
|
||||
(require 'org-macs))
|
||||
(require 'org)
|
||||
(require 'ol)
|
||||
(require 'org-roam-utils)
|
||||
|
||||
(defvar org-roam-find-file-hook)
|
||||
(defvar org-roam-directory)
|
||||
(defvar org-roam-verbose)
|
||||
(defvar org-agenda-files)
|
||||
|
||||
(declare-function org-roam-id-at-point "org-roam")
|
||||
(declare-function org-roam--list-all-files "org-roam")
|
||||
(declare-function org-roam-node-at-point "org-roam")
|
||||
|
||||
;;;; Options
|
||||
(defcustom org-roam-db-location (expand-file-name "org-roam.db" user-emacs-directory)
|
||||
"The path to file where the Org-roam database is stored.
|
||||
"The full path to file where the Org-roam database is stored.
|
||||
If this is non-nil, the Org-roam sqlite database is saved here.
|
||||
|
||||
It is the user's responsibility to set this correctly, especially
|
||||
when used with multiple Org-roam instances."
|
||||
@@ -44,44 +65,25 @@ when used with multiple Org-roam instances."
|
||||
|
||||
(defcustom org-roam-db-gc-threshold gc-cons-threshold
|
||||
"The value to temporarily set the `gc-cons-threshold' threshold to.
|
||||
During `org-roam-db-sync', Emacs can pause multiple times to
|
||||
perform garbage collection because of the large number of
|
||||
temporary structures generated (e.g. parsed ASTs).
|
||||
During large, heavy operations like `org-roam-db-sync',
|
||||
many GC operations happen because of the large number of
|
||||
temporary structures generated (e.g. parsed ASTs). Temporarily
|
||||
increasing `gc-cons-threshold' will help reduce the number of GC
|
||||
operations, at the cost of temporary memory usage.
|
||||
|
||||
`gc-cons-threshold' is temporarily set to
|
||||
`org-roam-db-gc-threshold' during this operation, and increasing
|
||||
`gc-cons-threshold' will help reduce the number of GC operations,
|
||||
at the cost of memory usage. Tweaking this value may lead to
|
||||
better overall performance.
|
||||
|
||||
For example, to reduce the number of GCs to the minimum, on
|
||||
machines with large memory one may set it to
|
||||
`most-positive-fixnum'."
|
||||
This defaults to the original value of `gc-cons-threshold', but
|
||||
tweaking this number may lead to better overall performance. For
|
||||
example, to reduce the number of GCs, one may set it to a large
|
||||
value like `most-positive-fixnum'."
|
||||
:type 'int
|
||||
:group 'org-roam)
|
||||
|
||||
(defcustom org-roam-db-node-include-function (lambda () t)
|
||||
"A custom function to check if the point contains a valid node.
|
||||
This function is called each time a node (both file and headline)
|
||||
is about to be saved into the Org-roam database.
|
||||
|
||||
If the function returns nil, Org-roam will skip the node. This
|
||||
function is useful for excluding certain nodes from the Org-roam
|
||||
database."
|
||||
"A custom function to check if the headline at point is a node."
|
||||
:type 'function
|
||||
:group 'org-roam)
|
||||
|
||||
(defcustom org-roam-db-update-on-save t
|
||||
"If t, update the Org-roam database upon saving the file.
|
||||
Disable this if your files are large and updating the database is
|
||||
slow."
|
||||
:type 'boolean
|
||||
:group 'org-roam)
|
||||
|
||||
;;; Variables
|
||||
(defconst org-roam-db-version 16)
|
||||
|
||||
;; TODO Rename this
|
||||
(defconst org-roam--sqlite-available-p
|
||||
(with-demoted-errors "Org-roam initialization: %S"
|
||||
(emacsql-sqlite-ensure-binary)
|
||||
@@ -90,7 +92,8 @@ slow."
|
||||
(defvar org-roam-db--connection (make-hash-table :test #'equal)
|
||||
"Database connection to Org-roam database.")
|
||||
|
||||
;;; Core Functions
|
||||
;;;; Core Functions
|
||||
|
||||
(defun org-roam-db--get-connection ()
|
||||
"Return the database connection, if any."
|
||||
(gethash (expand-file-name org-roam-directory)
|
||||
@@ -125,7 +128,7 @@ Performs a database upgrade when required."
|
||||
"and there is no upgrade path")))))))
|
||||
(org-roam-db--get-connection))
|
||||
|
||||
;;; Entrypoint: (org-roam-db-query)
|
||||
;;;; Entrypoint: (org-roam-db-query)
|
||||
(define-error 'emacsql-constraint "SQL constraint violation")
|
||||
(defun org-roam-db-query (sql &rest args)
|
||||
"Run SQL query on Org-roam database with ARGS.
|
||||
@@ -141,7 +144,7 @@ The query is expected to be able to fail, in this situation, run HANDLER."
|
||||
(emacsql-constraint
|
||||
(funcall handler err))))
|
||||
|
||||
;;; Schemata
|
||||
;;;; Schemata
|
||||
(defconst org-roam-db--table-schemata
|
||||
'((files
|
||||
[(file :unique :primary-key)
|
||||
@@ -227,8 +230,8 @@ the current `org-roam-directory'."
|
||||
(dolist (conn (hash-table-values org-roam-db--connection))
|
||||
(org-roam-db--close conn)))
|
||||
|
||||
;;; Database API
|
||||
;;;; Clearing
|
||||
;;;; Database API
|
||||
;;;;; Clearing
|
||||
(defun org-roam-db-clear-all ()
|
||||
"Clears all entries in the Org-roam cache."
|
||||
(interactive)
|
||||
@@ -245,7 +248,7 @@ If FILE is nil, clear the current buffer."
|
||||
:where (= file $s1)]
|
||||
file))
|
||||
|
||||
;;;; Updating tables
|
||||
;;;;; Updating tables
|
||||
(defun org-roam-db-insert-file ()
|
||||
"Update the files table for the current buffer.
|
||||
If UPDATE-P is non-nil, first remove the file in the database."
|
||||
@@ -270,7 +273,7 @@ If UPDATE-P is non-nil, first remove the file in the database."
|
||||
(org-format-time-string "%FT%T%z" time)))
|
||||
|
||||
(defun org-roam-db-node-p ()
|
||||
"Return t if headline at point is an Org-roam node, else return nil."
|
||||
"Return t if headline at point is a node, else return nil."
|
||||
(and (org-id-get)
|
||||
(not (cdr (assoc "ROAM_EXCLUDE" (org-entry-properties))))
|
||||
(funcall org-roam-db-node-include-function)))
|
||||
@@ -313,7 +316,7 @@ If UPDATE-P is non-nil, first remove the file in the database."
|
||||
(tags org-file-tags)
|
||||
(refs (org-entry-get (point) "ROAM_REFS"))
|
||||
(properties (org-entry-properties))
|
||||
(olp nil))
|
||||
(olp (org-get-outline-path)))
|
||||
(org-roam-db-query!
|
||||
(lambda (err)
|
||||
(lwarn 'org-roam :warning "%s for %s (%s) in %s"
|
||||
@@ -354,7 +357,7 @@ If UPDATE-P is non-nil, first remove the file in the database."
|
||||
:values $v1]
|
||||
rows)))))))))
|
||||
|
||||
(cl-defun org-roam-db-insert-node-data ()
|
||||
(defun org-roam-db-insert-node-data ()
|
||||
"Insert node data for headline at point into the Org-roam cache."
|
||||
(when-let ((id (org-id-get)))
|
||||
(let* ((file (buffer-file-name (buffer-base-buffer)))
|
||||
@@ -365,15 +368,9 @@ If UPDATE-P is non-nil, first remove the file in the database."
|
||||
(level (nth 1 heading-components))
|
||||
(scheduled (org-roam-db-get-scheduled-time))
|
||||
(deadline (org-roam-db-get-deadline-time))
|
||||
(title (or (nth 4 heading-components)
|
||||
(progn (lwarn 'org-roam :warning "Node in %s:%s:%s has no title, skipping..."
|
||||
file
|
||||
(line-number-at-pos)
|
||||
(1+ (- (point) (line-beginning-position))))
|
||||
(cl-return-from org-roam-db-insert-node-data))))
|
||||
(title (org-link-display-format (nth 4 heading-components)))
|
||||
(properties (org-entry-properties))
|
||||
(olp (org-get-outline-path nil 'use-cache))
|
||||
(title (org-link-display-format title)))
|
||||
(olp (org-get-outline-path)))
|
||||
(org-roam-db-query!
|
||||
(lambda (err)
|
||||
(lwarn 'org-roam :warning "%s for %s (%s) in %s"
|
||||
@@ -425,27 +422,16 @@ If UPDATE-P is non-nil, first remove the file in the database."
|
||||
(save-excursion
|
||||
(goto-char (org-element-property :begin link))
|
||||
(let ((type (org-element-property :type link))
|
||||
(path (org-element-property :path link))
|
||||
(properties (list :outline (ignore-errors
|
||||
;; This can error if link is not under any headline
|
||||
(org-get-outline-path 'with-self 'use-cache))))
|
||||
(dest (org-element-property :path link))
|
||||
(properties (list :outline (org-get-outline-path)))
|
||||
(source (org-roam-id-at-point)))
|
||||
;; For Org-ref links, we need to split the path into the cite keys
|
||||
(when (and (boundp 'org-ref-cite-types)
|
||||
(fboundp 'org-ref-split-and-strip-string)
|
||||
(member type org-ref-cite-types))
|
||||
(setq path (org-ref-split-and-strip-string path)))
|
||||
(unless (listp path)
|
||||
(setq path (list path)))
|
||||
(when (and source path)
|
||||
(when source
|
||||
(org-roam-db-query
|
||||
[:insert :into links
|
||||
:values $v1]
|
||||
(mapcar (lambda (p)
|
||||
(vector (point) source p type properties))
|
||||
path))))))
|
||||
(vector (point) source dest type properties))))))
|
||||
|
||||
;;;; Fetching
|
||||
;;;;; Fetching
|
||||
(defun org-roam-db--get-current-files ()
|
||||
"Return a hash-table of file to the hash of its file contents."
|
||||
(let ((current-files (org-roam-db-query [:select [file hash] :from files]))
|
||||
@@ -456,10 +442,6 @@ If UPDATE-P is non-nil, first remove the file in the database."
|
||||
|
||||
(defun org-roam-db--file-hash (&optional file-path)
|
||||
"Compute the hash of FILE-PATH, a file or current buffer."
|
||||
;; If it is a GPG encrypted file, we always want to compute the hash
|
||||
;; for the GPG encrypted file (undecrypted)
|
||||
(when (and (not file-path) (equal "gpg" (file-name-extension (buffer-file-name))))
|
||||
(setq file-path (buffer-file-name)))
|
||||
(if file-path
|
||||
(with-temp-buffer
|
||||
(set-buffer-multibyte nil)
|
||||
@@ -468,43 +450,18 @@ If UPDATE-P is non-nil, first remove the file in the database."
|
||||
(org-with-wide-buffer
|
||||
(secure-hash 'sha1 (current-buffer)))))
|
||||
|
||||
;;;; Synchronization
|
||||
(defun org-roam-db-update-file (&optional file-path)
|
||||
"Update Org-roam cache for FILE-PATH.
|
||||
If the file does not exist anymore, remove it from the cache.
|
||||
If the file exists, update the cache with information."
|
||||
(setq file-path (or file-path (buffer-file-name (buffer-base-buffer))))
|
||||
(let ((content-hash (org-roam-db--file-hash file-path))
|
||||
(db-hash (caar (org-roam-db-query [:select hash :from files
|
||||
:where (= file $s1)] file-path))))
|
||||
(unless (string= content-hash db-hash)
|
||||
(org-roam-with-file file-path nil
|
||||
(save-excursion
|
||||
(org-set-regexps-and-options 'tags-only)
|
||||
(org-roam-db-clear-file)
|
||||
(org-roam-db-insert-file)
|
||||
(org-roam-db-insert-file-node)
|
||||
(setq org-outline-path-cache nil)
|
||||
(org-roam-db-map-nodes
|
||||
(list #'org-roam-db-insert-node-data
|
||||
#'org-roam-db-insert-aliases
|
||||
#'org-roam-db-insert-tags
|
||||
#'org-roam-db-insert-refs))
|
||||
(setq org-outline-path-cache nil)
|
||||
(org-roam-db-map-links
|
||||
(list #'org-roam-db-insert-link)))))))
|
||||
|
||||
;;;;; Updating
|
||||
;;;###autoload
|
||||
(defun org-roam-db-sync (&optional force)
|
||||
"Synchronize the cache state with the current Org files on-disk.
|
||||
If FORCE, force a rebuild of the cache from scratch."
|
||||
(interactive "P")
|
||||
(org-roam-db--close) ;; Force a reconnect
|
||||
(when force (delete-file org-roam-db-location))
|
||||
(org-roam-db--close) ;; Force a reconnect
|
||||
(org-roam-db) ;; To initialize the database, no-op if already initialized
|
||||
(let* ((gc-cons-threshold org-roam-db-gc-threshold)
|
||||
(org-agenda-files nil)
|
||||
(org-roam-files (org-roam-list-files))
|
||||
(org-roam-files (org-roam--list-all-files))
|
||||
(current-files (org-roam-db--get-current-files))
|
||||
(modified-files nil))
|
||||
(dolist (file org-roam-files)
|
||||
@@ -527,90 +484,36 @@ If FORCE, force a rebuild of the cache from scratch."
|
||||
(dolist (file modified-files)
|
||||
(org-roam-db-update-file file))))))
|
||||
|
||||
;;;###autoload
|
||||
(define-minor-mode org-roam-db-autosync-mode
|
||||
"Global minor mode to keep your Org-roam session automatically synchronized.
|
||||
Through the session this will continue to setup your
|
||||
buffers (that are Org-roam file visiting), keep track of the
|
||||
related changes, maintain cache consistency and incrementally
|
||||
update the currently active database.
|
||||
(defun org-roam-db-update-file (&optional file-path)
|
||||
"Update Org-roam cache for FILE-PATH.
|
||||
If the file does not exist anymore, remove it from the cache.
|
||||
If the file exists, update the cache with information."
|
||||
(setq file-path (or file-path (buffer-file-name (buffer-base-buffer))))
|
||||
(let ((content-hash (org-roam-db--file-hash file-path))
|
||||
(db-hash (caar (org-roam-db-query [:select hash :from files
|
||||
:where (= file $s1)] file-path))))
|
||||
(unless (string= content-hash db-hash)
|
||||
(org-roam-with-file file-path nil
|
||||
(save-excursion
|
||||
(org-set-regexps-and-options 'tags-only)
|
||||
(org-roam-db-clear-file)
|
||||
(org-roam-db-insert-file)
|
||||
(org-roam-db-insert-file-node)
|
||||
(org-roam-db-map-nodes
|
||||
(list #'org-roam-db-insert-node-data
|
||||
#'org-roam-db-insert-aliases
|
||||
#'org-roam-db-insert-tags
|
||||
#'org-roam-db-insert-refs))
|
||||
(org-roam-db-map-links
|
||||
(list #'org-roam-db-insert-link)))))))
|
||||
|
||||
If you need to manually trigger resync of the currently active
|
||||
database, see `org-roam-db-sync' command."
|
||||
:group 'org-roam
|
||||
:global t
|
||||
:init-value nil
|
||||
(let ((enabled org-roam-db-autosync-mode))
|
||||
(cond
|
||||
(enabled
|
||||
(add-hook 'find-file-hook #'org-roam-db-autosync--setup-file-h)
|
||||
(add-hook 'kill-emacs-hook #'org-roam-db--close-all)
|
||||
(advice-add #'rename-file :after #'org-roam-db-autosync--rename-file-a)
|
||||
(advice-add #'delete-file :before #'org-roam-db-autosync--delete-file-a)
|
||||
(org-roam-db-sync))
|
||||
(t
|
||||
(remove-hook 'find-file-hook #'org-roam-db-autosync--setup-file-h)
|
||||
(remove-hook 'kill-emacs-hook #'org-roam-db--close-all)
|
||||
(advice-remove #'rename-file #'org-roam-db-autosync--rename-file-a)
|
||||
(advice-remove #'delete-file #'org-roam-db-autosync--delete-file-a)
|
||||
(org-roam-db--close-all)
|
||||
;; Disable local hooks for all org-roam buffers
|
||||
(dolist (buf (org-roam-buffer-list))
|
||||
(with-current-buffer buf
|
||||
(remove-hook 'after-save-hook #'org-roam-db-autosync--try-update-on-save-h t)))))))
|
||||
(defun org-roam-db--update-on-save-h ()
|
||||
"."
|
||||
(add-hook 'after-save-hook #'org-roam-db-update-file nil t))
|
||||
|
||||
;;;###autoload
|
||||
(defun org-roam-db-autosync-enable ()
|
||||
"Activate `org-roam-db-autosync-mode'."
|
||||
(org-roam-db-autosync-mode +1))
|
||||
(add-hook 'org-roam-find-file-hook #'org-roam-db--update-on-save-h)
|
||||
|
||||
(defun org-roam-db-autosync-disable ()
|
||||
"Deactivate `org-roam-db-autosync-mode'."
|
||||
(org-roam-db-autosync-mode -1))
|
||||
|
||||
(defun org-roam-db-autosync-toggle ()
|
||||
"Toggle `org-roam-db-autosync-mode' enabled/disabled."
|
||||
(org-roam-db-autosync-mode 'toggle))
|
||||
|
||||
(defun org-roam-db-autosync--delete-file-a (file &optional _trash)
|
||||
"Maintain cache consistency when file deletes.
|
||||
FILE is removed from the database."
|
||||
(when (and (not (auto-save-file-name-p file))
|
||||
(not (backup-file-name-p file))
|
||||
(org-roam-file-p file))
|
||||
(org-roam-db-clear-file (expand-file-name file))))
|
||||
|
||||
(defun org-roam-db-autosync--rename-file-a (old-file new-file-or-dir &rest _args)
|
||||
"Maintain cache consistency of file rename.
|
||||
OLD-FILE is cleared from the database, and NEW-FILE-OR-DIR is added."
|
||||
(let ((new-file (if (directory-name-p new-file-or-dir)
|
||||
(expand-file-name (file-name-nondirectory old-file) new-file-or-dir)
|
||||
new-file-or-dir)))
|
||||
(setq new-file (expand-file-name new-file))
|
||||
(setq old-file (expand-file-name old-file))
|
||||
(when (and (not (auto-save-file-name-p old-file))
|
||||
(not (auto-save-file-name-p new-file))
|
||||
(not (backup-file-name-p old-file))
|
||||
(not (backup-file-name-p new-file))
|
||||
(org-roam-file-p old-file))
|
||||
(org-roam-db-clear-file old-file))
|
||||
(when (org-roam-file-p new-file)
|
||||
(org-roam-db-update-file new-file))))
|
||||
|
||||
(defun org-roam-db-autosync--setup-file-h ()
|
||||
"Setup the current buffer if it visits an Org-roam file."
|
||||
(when (org-roam-file-p) (run-hooks 'org-roam-find-file-hook)))
|
||||
|
||||
(add-hook 'org-roam-find-file-hook #'org-roam-db-autosync--setup-update-on-save-h)
|
||||
(defun org-roam-db-autosync--setup-update-on-save-h ()
|
||||
"Setup the current buffer to update the DB after saving the current file."
|
||||
(add-hook 'after-save-hook #'org-roam-db-autosync--try-update-on-save-h nil t))
|
||||
|
||||
(defun org-roam-db-autosync--try-update-on-save-h ()
|
||||
"If appropriate, update the database for the current file after saving buffer."
|
||||
(when org-roam-db-update-on-save (org-roam-db-update-file)))
|
||||
|
||||
;;; Diagnostics
|
||||
;; Diagnostic Interactives
|
||||
(defun org-roam-db-diagnose-node ()
|
||||
"Print information about node at point."
|
||||
(interactive)
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
;;; org-roam-graph.el --- Basic graphing functionality for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
|
||||
;;; org-roam-graph.el --- Graphing API -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.1"))
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
@@ -27,14 +27,18 @@
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This extension implements capability to build and generate graphs in Org-roam
|
||||
;; with the help of Graphviz.
|
||||
;; This library provides graphing functionality for org-roam.
|
||||
;;
|
||||
;;; Code:
|
||||
(require 'xml) ;xml-escape-string
|
||||
(require 'org-roam)
|
||||
(eval-and-compile
|
||||
(require 'org-roam-macs))
|
||||
(require 'org-roam-db)
|
||||
|
||||
;;; Options
|
||||
;;;; Declarations
|
||||
(defvar org-roam-directory)
|
||||
|
||||
;;;; Options
|
||||
(defcustom org-roam-graph-viewer (executable-find "firefox")
|
||||
"Method to view the org-roam graph.
|
||||
It may be one of the following:
|
||||
@@ -113,58 +117,54 @@ All other values including nil will have no effect."
|
||||
(const :tag "no" nil))
|
||||
:group 'org-roam)
|
||||
|
||||
;;; Interactive command
|
||||
;;;###autoload
|
||||
(defun org-roam-graph (&optional arg node)
|
||||
"Build and possibly display a graph for NODE.
|
||||
ARG may be any of the following values:
|
||||
- nil show the graph.
|
||||
- `\\[universal-argument]' show the graph for NODE.
|
||||
- `\\[universal-argument]' N show the graph for NODE limiting nodes to N steps."
|
||||
(interactive
|
||||
(list current-prefix-arg
|
||||
(and current-prefix-arg
|
||||
(org-roam-node-at-point 'assert))))
|
||||
(let ((graph (cl-typecase arg
|
||||
(null (org-roam-graph--dot nil 'all-nodes))
|
||||
(cons (org-roam-graph--dot (org-roam-graph--connected-component
|
||||
(org-roam-node-id node) 0)))
|
||||
(integer (org-roam-graph--dot (org-roam-graph--connected-component
|
||||
(org-roam-node-id node) (abs arg)))))))
|
||||
(org-roam-graph--build graph #'org-roam-graph--open)))
|
||||
(defun org-roam-graph--dot-option (option &optional wrap-key wrap-val)
|
||||
"Return dot string of form KEY=VAL for OPTION cons.
|
||||
If WRAP-KEY is non-nil it wraps the KEY.
|
||||
If WRAP-VAL is non-nil it wraps the VAL."
|
||||
(concat wrap-key (car option) wrap-key
|
||||
"="
|
||||
wrap-val (cdr option) wrap-val))
|
||||
|
||||
;;; Generation and Build process
|
||||
(defun org-roam-graph--build (graph &optional callback)
|
||||
"Generate the GRAPH, and execute CALLBACK when process exits successfully.
|
||||
CALLBACK is passed the graph file as its sole argument."
|
||||
(unless (stringp org-roam-graph-executable)
|
||||
(user-error "`org-roam-graph-executable' is not a string"))
|
||||
(unless (executable-find org-roam-graph-executable)
|
||||
(user-error (concat "Cannot find executable \"%s\" to generate the graph. "
|
||||
"Please adjust `org-roam-graph-executable'")
|
||||
org-roam-graph-executable))
|
||||
(let* ((temp-dot (make-temp-file "graph." nil ".dot" graph))
|
||||
(temp-graph (make-temp-file "graph." nil (concat "." org-roam-graph-filetype))))
|
||||
(org-roam-message "building graph")
|
||||
(make-process
|
||||
:name "*org-roam-graph--build-process*"
|
||||
:buffer "*org-roam-graph--build-process*"
|
||||
:command `(,org-roam-graph-executable ,temp-dot "-T" ,org-roam-graph-filetype "-o" ,temp-graph)
|
||||
:sentinel (when callback
|
||||
(lambda (process _event)
|
||||
(when (= 0 (process-exit-status process))
|
||||
(funcall callback temp-graph)))))))
|
||||
(defun org-roam-graph--connected-component (id distance)
|
||||
"Return the edges for all nodes reachable from/connected to ID.
|
||||
DISTANCE is the maximum distance away from the root node."
|
||||
(let* ((query
|
||||
(if (= distance 0)
|
||||
"
|
||||
WITH RECURSIVE
|
||||
links_of(source, dest) AS
|
||||
(SELECT source, dest FROM links UNION
|
||||
SELECT dest, source FROM links),
|
||||
connected_component(source) AS
|
||||
(SELECT dest FROM links_of WHERE source = $s1 UNION
|
||||
SELECT dest FROM links_of JOIN connected_component USING(source))
|
||||
SELECT source, dest, type FROM links WHERE source IN connected_component OR dest IN connected_component;"
|
||||
"
|
||||
WITH RECURSIVE
|
||||
links_of(source, dest) AS
|
||||
(SELECT source, dest FROM links UNION
|
||||
SELECT dest, source FROM links),
|
||||
connected_component(source, trace) AS
|
||||
(VALUES ($s1 , json_array($s1)) UNION
|
||||
SELECT lo.dest, json_insert(cc.trace, '$[' || json_array_length(cc.trace) || ']', lo.dest) FROM
|
||||
connected_component AS cc JOIN links_of AS lo USING(source)
|
||||
WHERE (
|
||||
-- Avoid cycles by only visiting each node once.
|
||||
(SELECT count(*) FROM json_each(cc.trace) WHERE json_each.value == lo.dest) == 0
|
||||
-- Note: BFS is cut off early here.
|
||||
AND json_array_length(cc.trace) < $s2)),
|
||||
nodes(source) as (SELECT DISTINCT source
|
||||
FROM connected_component GROUP BY source ORDER BY min(json_array_length(trace)))
|
||||
SELECT source, dest, type FROM links WHERE source IN nodes OR dest IN nodes;")))
|
||||
(org-roam-db-query query id distance)))
|
||||
|
||||
(defun org-roam-graph--dot (&optional edges all-nodes)
|
||||
"Build the graphviz given the EDGES of the graph.
|
||||
If ALL-NODES, include also nodes without edges."
|
||||
(let ((org-roam-directory-temp org-roam-directory)
|
||||
(nodes-table (make-hash-table :test #'equal))
|
||||
(nodes-table (org-roam--nodes-table))
|
||||
(seen-nodes (list))
|
||||
(edges (or edges (org-roam-db-query [:select :distinct [source dest type] :from links]))))
|
||||
(pcase-dolist (`(,id ,file ,title)
|
||||
(org-roam-db-query [:select [id file title] :from nodes]))
|
||||
(puthash id (org-roam-node-create :file file :id id :title title) nodes-table))
|
||||
(with-temp-buffer
|
||||
(setq-local org-roam-directory org-roam-directory-temp)
|
||||
(insert "digraph \"org-roam\" {\n")
|
||||
@@ -194,60 +194,17 @@ If ALL-NODES, include also nodes without edges."
|
||||
(insert "}")
|
||||
(buffer-string))))
|
||||
|
||||
(defun org-roam-graph--connected-component (id distance)
|
||||
"Return the edges for all nodes reachable from/connected to ID.
|
||||
DISTANCE is the maximum distance away from the root node."
|
||||
(let* ((query
|
||||
(if (= distance 0)
|
||||
"
|
||||
WITH RECURSIVE
|
||||
links_of(source, dest) AS
|
||||
(SELECT source, dest FROM links UNION
|
||||
SELECT dest, source FROM links),
|
||||
connected_component(source) AS
|
||||
(SELECT dest FROM links_of WHERE source = $s1 UNION
|
||||
SELECT dest FROM links_of JOIN connected_component USING(source))
|
||||
SELECT DISTINCT source, dest, type FROM links
|
||||
WHERE source IN connected_component OR dest IN connected_component;"
|
||||
"
|
||||
WITH RECURSIVE
|
||||
links_of(source, dest) AS
|
||||
(SELECT source, dest FROM links UNION
|
||||
SELECT dest, source FROM links),
|
||||
connected_component(source, trace) AS
|
||||
(VALUES ($s1 , json_array($s1)) UNION
|
||||
SELECT lo.dest, json_insert(cc.trace, '$[' || json_array_length(cc.trace) || ']', lo.dest) FROM
|
||||
connected_component AS cc JOIN links_of AS lo USING(source)
|
||||
WHERE (
|
||||
-- Avoid cycles by only visiting each node once.
|
||||
(SELECT count(*) FROM json_each(cc.trace) WHERE json_each.value == lo.dest) == 0
|
||||
-- Note: BFS is cut off early here.
|
||||
AND json_array_length(cc.trace) < $s2)),
|
||||
nodes(source) as (SELECT DISTINCT source
|
||||
FROM connected_component GROUP BY source ORDER BY min(json_array_length(trace)))
|
||||
SELECT DISTINCT source, dest, type FROM links WHERE source IN nodes OR dest IN nodes;")))
|
||||
(org-roam-db-query query id distance)))
|
||||
|
||||
(defun org-roam-graph--dot-option (option &optional wrap-key wrap-val)
|
||||
"Return dot string of form KEY=VAL for OPTION cons.
|
||||
If WRAP-KEY is non-nil it wraps the KEY.
|
||||
If WRAP-VAL is non-nil it wraps the VAL."
|
||||
(concat wrap-key (car option) wrap-key
|
||||
"="
|
||||
wrap-val (cdr option) wrap-val))
|
||||
|
||||
(defun org-roam-graph--format-node (node type)
|
||||
"Return a graphviz NODE with TYPE.
|
||||
Handles both Org-roam nodes, and string nodes (e.g. urls)."
|
||||
(let (node-id node-properties)
|
||||
(if (org-roam-node-p node)
|
||||
(let* ((title (org-roam-quote-string (org-roam-node-title node)))
|
||||
(shortened-title
|
||||
(org-roam-quote-string
|
||||
(pcase org-roam-graph-shorten-titles
|
||||
(`truncate (truncate-string-to-width title org-roam-graph-max-title-length nil nil "..."))
|
||||
(`wrap (s-word-wrap org-roam-graph-max-title-length title))
|
||||
(_ title)))))
|
||||
(shortened-title (org-roam-quote-string
|
||||
(pcase org-roam-graph-shorten-titles
|
||||
(`truncate (org-roam-truncate org-roam-graph-max-title-length title))
|
||||
(`wrap (s-word-wrap org-roam-graph-max-title-length title))
|
||||
(_ title)))))
|
||||
(setq node-id (org-roam-node-id node)
|
||||
node-properties `(("label" . ,shortened-title)
|
||||
("URL" . ,(concat "org-protocol://roam-node?node="
|
||||
@@ -264,6 +221,27 @@ Handles both Org-roam nodes, and string nodes (e.g. urls)."
|
||||
(append (cdr (assoc type org-roam-graph-node-extra-config))
|
||||
node-properties) ","))))
|
||||
|
||||
(defun org-roam-graph--build (graph &optional callback)
|
||||
"Generate the GRAPH, and execute CALLBACK when process exits successfully.
|
||||
CALLBACK is passed the graph file as its sole argument."
|
||||
(unless (stringp org-roam-graph-executable)
|
||||
(user-error "`org-roam-graph-executable' is not a string"))
|
||||
(unless (executable-find org-roam-graph-executable)
|
||||
(user-error (concat "Cannot find executable \"%s\" to generate the graph. "
|
||||
"Please adjust `org-roam-graph-executable'")
|
||||
org-roam-graph-executable))
|
||||
(let* ((temp-dot (make-temp-file "graph." nil ".dot" graph))
|
||||
(temp-graph (make-temp-file "graph." nil (concat "." org-roam-graph-filetype))))
|
||||
(org-roam-message "building graph")
|
||||
(make-process
|
||||
:name "*org-roam-graph--build-process*"
|
||||
:buffer "*org-roam-graph--build-process*"
|
||||
:command `(,org-roam-graph-executable ,temp-dot "-T" ,org-roam-graph-filetype "-o" ,temp-graph)
|
||||
:sentinel (when callback
|
||||
(lambda (process _event)
|
||||
(when (= 0 (process-exit-status process))
|
||||
(funcall callback temp-graph)))))))
|
||||
|
||||
(defun org-roam-graph--open (file)
|
||||
"Open FILE using `org-roam-graph-viewer' with `view-file' as a fallback."
|
||||
(pcase org-roam-graph-viewer
|
||||
@@ -277,6 +255,26 @@ Handles both Org-roam nodes, and string nodes (e.g. urls)."
|
||||
('nil (view-file file))
|
||||
(_ (signal 'wrong-type-argument `((functionp stringp null) ,org-roam-graph-viewer)))))
|
||||
|
||||
;;;; Commands
|
||||
;;;###autoload
|
||||
(defun org-roam-graph (&optional arg node)
|
||||
"Build and possibly display a graph for NODE.
|
||||
ARG may be any of the following values:
|
||||
- nil show the graph.
|
||||
- `\\[universal-argument]' show the graph for NODE.
|
||||
- `\\[universal-argument]' N show the graph for NODE limiting nodes to N steps."
|
||||
(interactive
|
||||
(list current-prefix-arg
|
||||
(and current-prefix-arg
|
||||
(org-roam-node-at-point 'assert))))
|
||||
(let ((graph (cl-typecase arg
|
||||
(null (org-roam-graph--dot nil 'all-nodes))
|
||||
(cons (org-roam-graph--dot (org-roam-graph--connected-component
|
||||
(org-roam-node-id node) 0)))
|
||||
(integer (org-roam-graph--dot (org-roam-graph--connected-component
|
||||
(org-roam-node-id node) (abs arg)))))))
|
||||
(org-roam-graph--build graph #'org-roam-graph--open)))
|
||||
|
||||
|
||||
(provide 'org-roam-graph)
|
||||
|
||||
90
org-roam-macs.el
Normal file
90
org-roam-macs.el
Normal file
@@ -0,0 +1,90 @@
|
||||
;;; org-roam-macs.el --- Macros/utility functions -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
;; This program is free software; you can redistribute it and/or modify
|
||||
;; it under the terms of the GNU General Public License as published by
|
||||
;; the Free Software Foundation; either version 3, or (at your option)
|
||||
;; any later version.
|
||||
;;
|
||||
;; This program is distributed in the hope that it will be useful,
|
||||
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
;; GNU General Public License for more details.
|
||||
;;
|
||||
;; You should have received a copy of the GNU General Public License
|
||||
;; along with GNU Emacs; see the file COPYING. If not, write to the
|
||||
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
||||
;; Boston, MA 02110-1301, USA.
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This library implements macros used throughout org-roam.
|
||||
;;
|
||||
;;; Code:
|
||||
(defmacro org-roam-plist-map! (fn plist)
|
||||
"Map FN over PLIST, modifying it in-place."
|
||||
(declare (indent 1))
|
||||
(let ((plist-var (make-symbol "plist"))
|
||||
(k (make-symbol "k"))
|
||||
(v (make-symbol "v")))
|
||||
`(let ((,plist-var (copy-sequence ,plist)))
|
||||
(while ,plist-var
|
||||
(setq ,k (pop ,plist-var))
|
||||
(setq ,v (pop ,plist-var))
|
||||
(setq ,plist (plist-put ,plist ,k (funcall ,fn ,k ,v)))))))
|
||||
|
||||
(defmacro org-roam-with-file (file keep-buf-p &rest body)
|
||||
"Execute BODY within FILE.
|
||||
If FILE is nil, execute BODY in the current buffer.
|
||||
Kills the buffer if KEEP-BUF-P is nil, and FILE is not yet visited."
|
||||
(declare (indent 2) (debug t))
|
||||
`(let* (new-buf
|
||||
(auto-mode-alist nil)
|
||||
(buf (or (and (not ,file)
|
||||
(current-buffer)) ;If FILE is nil, use current buffer
|
||||
(find-buffer-visiting ,file) ; If FILE is already visited, find buffer
|
||||
(progn
|
||||
(setq new-buf t)
|
||||
(find-file-noselect ,file)))) ; Else, visit FILE and return buffer
|
||||
res)
|
||||
(with-current-buffer buf
|
||||
(unless (equal major-mode 'org-mode)
|
||||
(delay-mode-hooks
|
||||
(let ((org-inhibit-startup t)
|
||||
(org-agenda-files nil))
|
||||
(org-mode))))
|
||||
(setq res (progn ,@body))
|
||||
(unless (and new-buf (not ,keep-buf-p))
|
||||
(save-buffer)))
|
||||
(if (and new-buf (not ,keep-buf-p))
|
||||
(when (find-buffer-visiting ,file)
|
||||
(kill-buffer (find-buffer-visiting ,file))))
|
||||
res))
|
||||
|
||||
(defmacro org-roam-with-temp-buffer (file &rest body)
|
||||
"Execute BODY within a temp buffer.
|
||||
Like `with-temp-buffer', but propagates `org-roam-directory'.
|
||||
If FILE, set `default-directory' to FILE's directory and insert its contents."
|
||||
(declare (indent 1) (debug t))
|
||||
(let ((current-org-roam-directory (make-symbol "current-org-roam-directory")))
|
||||
`(let ((,current-org-roam-directory org-roam-directory))
|
||||
(with-temp-buffer
|
||||
(let ((org-roam-directory ,current-org-roam-directory))
|
||||
(delay-mode-hooks (org-mode))
|
||||
(when ,file
|
||||
(insert-file-contents ,file)
|
||||
(setq-local default-directory (file-name-directory ,file)))
|
||||
,@body)))))
|
||||
|
||||
(provide 'org-roam-macs)
|
||||
|
||||
;;; org-roam-macs.el ends here
|
||||
@@ -5,7 +5,7 @@
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
@@ -27,18 +27,16 @@
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This is a special library provided for the v1 users of this package. It's
|
||||
;; purpose is to ease the transition from v1 to v2, by providing migration
|
||||
;; utilities to convert from v1 notes to v2 nodes.
|
||||
;; To ease transition from v1 to v2, we provide various migration utilities.
|
||||
;; This library helps convert v1 notes to v2, and informs the user.
|
||||
;;
|
||||
;;; Code:
|
||||
(require 'org-roam)
|
||||
|
||||
;;;; Dependencies
|
||||
;;;;
|
||||
;;; v1 breaking warning
|
||||
(defvar org-roam-v2-ack nil
|
||||
"When set to t, won't display the annoying warning message about the upgrade.
|
||||
Need to be set before the package is loaded, otherwise won't take
|
||||
any affect.")
|
||||
(require 'org-roam-db)
|
||||
|
||||
(defvar org-roam-v2-ack nil)
|
||||
|
||||
(unless org-roam-v2-ack
|
||||
(lwarn 'org-roam :error "
|
||||
@@ -48,17 +46,12 @@ WARNING: You're now on Org-roam v2!
|
||||
|
||||
You may have arrived here from a package upgrade. Please read the
|
||||
wiki entry at
|
||||
%s
|
||||
https://github.com/org-roam/org-roam/wiki/Hitchhiker's-Rough-Guide-to-Org-roam-V2
|
||||
for an overview of the major changes.
|
||||
|
||||
Notes taken in v1 are incompatible with v2, but you can upgrade
|
||||
Notes taken in v1 are incompatible with v1, but you can upgrade
|
||||
them to the v2 format via a simple command. To migrate your
|
||||
notes, first make sure you're on at least Org 9.4 (check with
|
||||
C-h v org-version) and set your org-roam-directory to your notes:
|
||||
|
||||
(setq org-roam-directory \"path/to/org/files\")
|
||||
|
||||
then, run:
|
||||
notes, run:
|
||||
|
||||
M-x org-roam-migrate-wizard
|
||||
|
||||
@@ -73,10 +66,8 @@ this warning. You can do so by adding:
|
||||
|
||||
To your init file.
|
||||
|
||||
"
|
||||
"https://github.com/org-roam/org-roam/wiki/Hitchhiker's-Rough-Guide-to-Org-roam-V2"))
|
||||
"))
|
||||
|
||||
;;; Migration wizard (v1 -> v2)
|
||||
;;;###autoload
|
||||
(defun org-roam-migrate-wizard ()
|
||||
"Migrate all notes from to be compatible with Org-roam v2.
|
||||
@@ -87,27 +78,31 @@ To your init file.
|
||||
(when (yes-or-no-p "Org-roam will now convert all your notes from v1 to v2.
|
||||
This will take a while. Are you sure you want to do this?")
|
||||
;; Back up notes
|
||||
(let ((backup-dir (expand-file-name "org-roam.bak"
|
||||
(file-name-directory (directory-file-name org-roam-directory)))))
|
||||
(let* ((parent-dir (f-parent org-roam-directory))
|
||||
(backup-dir (expand-file-name "org-roam.bak" parent-dir))
|
||||
(debug-dir (expand-file-name "org-roam.debug" parent-dir)))
|
||||
(message "Backing up files to %s" backup-dir)
|
||||
(copy-directory org-roam-directory backup-dir))
|
||||
(condition-case err
|
||||
(progn
|
||||
;; Convert v1 to v2
|
||||
(dolist (f (org-roam--list-all-files))
|
||||
(org-roam-with-file f nil
|
||||
(org-roam-migrate-v1-to-v2)))
|
||||
;; Rebuild cache
|
||||
(org-roam-db-sync 'force)
|
||||
|
||||
;; Upgrade database to v2
|
||||
(org-roam-db-sync 'force)
|
||||
|
||||
;; Convert v1 to v2
|
||||
(dolist (f (org-roam-list-files))
|
||||
(org-roam-with-file f nil
|
||||
(org-roam-migrate-v1-to-v2)))
|
||||
|
||||
;; Rebuild cache
|
||||
(org-roam-db-sync 'force)
|
||||
|
||||
;;Replace all file links with ID links
|
||||
(dolist (f (org-roam-list-files))
|
||||
(org-roam-with-file f nil
|
||||
(org-roam-migrate-replace-file-links-with-id)
|
||||
(save-buffer)))))
|
||||
;;Replace all file links with ID links
|
||||
(dolist (f (org-roam--list-all-files))
|
||||
(org-roam-with-file f nil
|
||||
(org-roam-migrate-replace-file-links-with-id)
|
||||
(save-buffer))))
|
||||
(t
|
||||
(rename-file org-roam-directory debug-dir)
|
||||
(rename-file backup-dir org-roam-directory)
|
||||
(lwarn 'org-roam :warning (format "The migration wizard failed with error:\n%s\n%s"
|
||||
(error-message-string err)
|
||||
"Your files have been restored, consider filing an issue.\n"))))))
|
||||
|
||||
(defun org-roam-migrate-v1-to-v2 ()
|
||||
"Convert the current buffer to v2 format."
|
||||
@@ -139,11 +134,7 @@ This will take a while. Are you sure you want to do this?")
|
||||
;; Replace #+roam_tags into #+filetags
|
||||
(org-with-point-at 1
|
||||
(let* ((roam-tags (org-roam-migrate-get-prop-list "ROAM_TAGS"))
|
||||
(file-tags (cl-mapcan (lambda (value)
|
||||
(cl-mapcan
|
||||
(lambda (k) (org-split-string k ":"))
|
||||
(split-string value)))
|
||||
(org-roam-migrate-get-prop-list "FILETAGS")))
|
||||
(file-tags (org-roam-migrate-get-prop-list "FILETAGS"))
|
||||
(tags (append roam-tags file-tags))
|
||||
(tags (seq-map (lambda (tag)
|
||||
(replace-regexp-in-string
|
||||
@@ -152,7 +143,7 @@ This will take a while. Are you sure you want to do this?")
|
||||
tag)) tags))
|
||||
(tags (seq-uniq tags)))
|
||||
(when tags
|
||||
(org-roam-migrate-prop-set "filetags" (org-make-tag-string tags))))
|
||||
(org-roam-migrate-prop-set "filetags" (string-join tags " "))))
|
||||
(let ((case-fold-search t))
|
||||
(org-with-point-at 1
|
||||
(while (re-search-forward "^#\\+roam_tags:" (point-max) t)
|
||||
@@ -203,8 +194,7 @@ If the property is already set, replace its value."
|
||||
:where (= file $s1)
|
||||
:and (= level 0)] path))))
|
||||
(set-match-data mdata)
|
||||
(replace-match (org-link-make-string (concat "id:" node-id)
|
||||
desc) nil t)))))))
|
||||
(replace-match (org-link-make-string (concat "id:" node-id)) nil t)))))))
|
||||
|
||||
(provide 'org-roam-migrate)
|
||||
;;; org-roam-migrate.el ends here
|
||||
|
||||
485
org-roam-mode.el
485
org-roam-mode.el
@@ -1,11 +1,10 @@
|
||||
;;; org-roam-mode.el --- Major mode for special Org-roam buffers -*- lexical-binding: t -*-
|
||||
|
||||
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;;; org-roam-mode.el --- create and refresh Org-roam buffers -*- lexical-binding: t -*-
|
||||
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
@@ -27,26 +26,18 @@
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This module implements `org-roam-mode', which is a major mode that used by
|
||||
;; special Org-roam buffers to display various content in a section-like manner
|
||||
;; about the nodes and relevant to them information (e.g. backlinks) with which
|
||||
;; the user can interact with.
|
||||
;; This library implements the abstract major-mode `org-roam-mode', from which
|
||||
;; almost all other Org-roam major-modes derive.
|
||||
;;
|
||||
;;; Code:
|
||||
(require 'org-roam)
|
||||
(require 'magit-section)
|
||||
|
||||
;;;; Declarations
|
||||
(defvar org-ref-buffer-hacked)
|
||||
(require 'org-roam-utils)
|
||||
|
||||
;;; Options
|
||||
(defcustom org-roam-mode-section-functions (list #'org-roam-backlinks-section
|
||||
#'org-roam-reflinks-section)
|
||||
"Functions that insert sections in the `org-roam-mode' based buffers.
|
||||
Each function is called with one argument, which is an
|
||||
`org-roam-node' for which the buffer will be constructed for.
|
||||
Normally this node is `org-roam-buffer-current-node'."
|
||||
:group 'org-roam
|
||||
:type 'hook)
|
||||
(defvar org-roam-directory)
|
||||
(defvar org-roam-find-file-hook)
|
||||
|
||||
(declare-function org-roam-node-at-point "org-roam")
|
||||
|
||||
;;; Faces
|
||||
(defface org-roam-header-line
|
||||
@@ -128,150 +119,91 @@ and `:slant'."
|
||||
"Face for the dimmer part of the widgets."
|
||||
:group 'org-roam-faces)
|
||||
|
||||
;;; Major mode
|
||||
;;; Variables
|
||||
(defvar org-roam-current-node nil
|
||||
"The current node at point.")
|
||||
|
||||
(defvar org-roam-current-directory nil
|
||||
"The `org-roam-directory' value for the current node.")
|
||||
|
||||
(defcustom org-roam-mode-section-functions (list #'org-roam-backlinks-section
|
||||
#'org-roam-reflinks-section)
|
||||
"Functions which insert sections of the `org-roam-buffer'.
|
||||
Each function is called with one argument, which is the current org-roam node at point."
|
||||
:group 'org-roam
|
||||
:type 'hook)
|
||||
|
||||
;;; The mode
|
||||
(defvar org-roam-mode-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(set-keymap-parent map magit-section-mode-map)
|
||||
(define-key map [C-return] 'org-roam-buffer-visit-thing)
|
||||
(define-key map (kbd "C-m") 'org-roam-buffer-visit-thing)
|
||||
(define-key map [remap revert-buffer] 'org-roam-buffer-refresh)
|
||||
(define-key map [C-return] 'org-roam-visit-thing)
|
||||
(define-key map (kbd "C-m") 'org-roam-visit-thing)
|
||||
(define-key map [remap revert-buffer] 'org-roam-buffer-render)
|
||||
map)
|
||||
"Parent keymap for all keymaps of modes derived from `org-roam-mode'.")
|
||||
|
||||
(define-derived-mode org-roam-mode magit-section-mode "Org-roam"
|
||||
"Major mode for displaying relevant information about Org-roam nodes.
|
||||
This mode is used by special Org-roam buffers, such as persistent
|
||||
`org-roam-buffer' and dedicated Org-roam buffers
|
||||
\(`org-roam-buffer-display-dedicated'), which render the
|
||||
information in a section-like manner (see
|
||||
`org-roam-mode-section-functions'), with which the user can
|
||||
interact with."
|
||||
"Major mode for Org-roam's buffer."
|
||||
:group 'org-roam
|
||||
(face-remap-add-relative 'header-line 'org-roam-header-line))
|
||||
|
||||
;;; Buffers
|
||||
(defvar org-roam-buffer-current-node nil
|
||||
"The node for which an `org-roam-mode' based buffer displays its contents.
|
||||
This set both, locally and globally. Normally the local value is
|
||||
only set in the `org-roam-mode' based buffers, while the global
|
||||
value shows the current node in the persistent `org-roam-buffer'.")
|
||||
|
||||
(put 'org-roam-buffer-current-node 'permanent-local t)
|
||||
|
||||
(defvar org-roam-buffer-current-directory nil
|
||||
"The `org-roam-directory' value of `org-roam-buffer-current-node'.
|
||||
Set both, locally and globally in the same way as `org-roam-buffer-current-node'.")
|
||||
|
||||
(put 'org-roam-buffer-current-directory 'permanent-local t)
|
||||
|
||||
;;;; Library
|
||||
(defun org-roam-buffer-visit-thing ()
|
||||
;;; Key functions
|
||||
(defun org-roam-visit-thing ()
|
||||
"This is a placeholder command.
|
||||
Where applicable, section-specific keymaps bind another command
|
||||
which visits the thing at point."
|
||||
(interactive)
|
||||
(user-error "There is no thing at point that could be visited"))
|
||||
|
||||
(defun org-roam-buffer-file-at-point (&optional assert)
|
||||
"Return the file at point in the current `org-roam-mode' based buffer.
|
||||
If ASSERT, throw an error."
|
||||
(if-let ((file (magit-section-case
|
||||
(org-roam-node-section (org-roam-node-file (oref it node)))
|
||||
(org-roam-grep-section (oref it file))
|
||||
(org-roam-preview-section (oref it file))
|
||||
(t (cl-assert (derived-mode-p 'org-roam-mode))))))
|
||||
file
|
||||
(when assert
|
||||
(user-error "No file at point"))))
|
||||
|
||||
(defun org-roam-buffer-refresh ()
|
||||
"Refresh the contents of the currently selected Org-roam buffer."
|
||||
(defun org-roam-buffer-render ()
|
||||
"Render the current node at point."
|
||||
(interactive)
|
||||
(cl-assert (derived-mode-p 'org-roam-mode))
|
||||
(save-excursion (org-roam-buffer-render-contents)))
|
||||
(when (derived-mode-p 'org-roam-mode)
|
||||
(let ((inhibit-read-only t))
|
||||
(erase-buffer)
|
||||
(setq-local default-directory org-roam-current-directory)
|
||||
(setq-local org-roam-directory org-roam-current-directory)
|
||||
(org-roam-set-header-line-format (org-roam-node-title org-roam-current-node))
|
||||
(magit-insert-section (org-roam)
|
||||
(magit-insert-heading)
|
||||
(run-hook-with-args 'org-roam-mode-section-functions org-roam-current-node)))))
|
||||
|
||||
(defun org-roam-buffer-render-contents ()
|
||||
"Recompute and render the contents of an Org-roam buffer.
|
||||
Assumes that the current buffer is an `org-roam-mode' based
|
||||
buffer."
|
||||
(let ((inhibit-read-only t))
|
||||
(erase-buffer)
|
||||
(org-roam-mode)
|
||||
(setq-local default-directory org-roam-buffer-current-directory)
|
||||
(setq-local org-roam-directory org-roam-buffer-current-directory)
|
||||
(org-roam-buffer-set-header-line-format
|
||||
(org-roam-node-title org-roam-buffer-current-node))
|
||||
(magit-insert-section (org-roam)
|
||||
(magit-insert-heading)
|
||||
(run-hook-with-args 'org-roam-mode-section-functions org-roam-buffer-current-node))
|
||||
(goto-char 0)))
|
||||
(defun org-roam-buffer ()
|
||||
"Launch an Org-roam buffer for the current node at point."
|
||||
(interactive)
|
||||
(if-let ((node (org-roam-node-at-point))
|
||||
(source-org-roam-directory org-roam-directory))
|
||||
(progn
|
||||
(let ((buffer (get-buffer-create
|
||||
(concat "org-roam: "
|
||||
(file-relative-name (buffer-file-name) org-roam-directory)))))
|
||||
(with-current-buffer buffer
|
||||
(org-roam-mode)
|
||||
(setq-local org-roam-current-node node)
|
||||
(setq-local org-roam-current-directory source-org-roam-directory)
|
||||
(org-roam-buffer-render))
|
||||
(switch-to-buffer-other-window buffer)))
|
||||
(user-error "No node at point")))
|
||||
|
||||
(defun org-roam-buffer-set-header-line-format (string)
|
||||
"Set the header-line using STRING.
|
||||
If the `face' property of any part of STRING is already set, then
|
||||
that takes precedence. Also pad the left side of STRING so that
|
||||
it aligns with the text area."
|
||||
(setq-local header-line-format
|
||||
(concat (propertize " " 'display '(space :align-to 0))
|
||||
string)))
|
||||
|
||||
;;;; Dedicated buffer
|
||||
;;;###autoload
|
||||
(defun org-roam-buffer-display-dedicated (node)
|
||||
"Launch NODE dedicated Org-roam buffer.
|
||||
Unlike the persistent `org-roam-buffer', the contents of this
|
||||
buffer won't be automatically changed and will be held in place.
|
||||
|
||||
In interactive calls prompt to select NODE, unless called with
|
||||
`universal-argument', in which case NODE will be set to
|
||||
`org-roam-node-at-point'."
|
||||
(interactive
|
||||
(list (if current-prefix-arg
|
||||
(org-roam-node-at-point 'assert)
|
||||
(org-roam-node-read nil nil nil 'require-match))))
|
||||
(let ((buffer (get-buffer-create (org-roam-buffer--dedicated-name node))))
|
||||
(with-current-buffer buffer
|
||||
(setq-local org-roam-buffer-current-node node)
|
||||
(setq-local org-roam-buffer-current-directory org-roam-directory)
|
||||
(org-roam-buffer-render-contents))
|
||||
(display-buffer buffer)))
|
||||
|
||||
(defun org-roam-buffer--dedicated-name (node)
|
||||
"Construct buffer name for NODE dedicated Org-roam buffer."
|
||||
(let ((title (org-roam-node-title node))
|
||||
(filename (file-relative-name (org-roam-node-file node) org-roam-directory)))
|
||||
(format "*org-roam: %s<%s>*" title filename)))
|
||||
|
||||
(defun org-roam-buffer-dedicated-p (&optional buffer)
|
||||
"Return t if an Org-roam BUFFER is a node dedicated one.
|
||||
See `org-roam-buffer-display-dedicated' for more details.
|
||||
If BUFFER is nil, default it to `current-buffer'."
|
||||
(or buffer (setq buffer (current-buffer)))
|
||||
(string-match-p (concat "^" (regexp-quote "*org-roam: "))
|
||||
(buffer-name buffer)))
|
||||
|
||||
;;;; Persistent buffer
|
||||
;;; Persistent buffer
|
||||
(defvar org-roam-buffer "*org-roam*"
|
||||
"The persistent Org-roam buffer name. Must be surround with \"*\".
|
||||
The content inside of this buffer will be automatically updated
|
||||
to the nearest node at point that comes from the current buffer.
|
||||
To toggle its display use `org-roam-buffer-toggle' command.")
|
||||
"The persistent Org-roam buffer name.")
|
||||
|
||||
(defun org-roam-buffer-toggle ()
|
||||
"Toggle display of the persistent `org-roam-buffer'."
|
||||
(interactive)
|
||||
(pcase (org-roam-buffer--visibility)
|
||||
('visible
|
||||
(progn
|
||||
(delete-window (get-buffer-window org-roam-buffer))
|
||||
(remove-hook 'post-command-hook #'org-roam-buffer--redisplay-h)))
|
||||
((or 'exists 'none)
|
||||
(progn
|
||||
(display-buffer (get-buffer-create org-roam-buffer))
|
||||
(org-roam-buffer-persistent-redisplay)))))
|
||||
(defun org-roam-buffer--post-command-h ()
|
||||
"Reconstructs the Org-roam buffer.
|
||||
This needs to be quick or infrequent, because this is run at
|
||||
`post-command-hook'. If REDISPLAY, force an update of
|
||||
the Org-roam buffer."
|
||||
(when (get-buffer-window org-roam-buffer)
|
||||
(when-let ((node (org-roam-node-at-point)))
|
||||
(unless (equal node org-roam-current-node)
|
||||
(setq org-roam-current-node node)
|
||||
(setq org-roam-current-directory org-roam-directory)
|
||||
(org-roam-buffer-persistent-redisplay)))))
|
||||
|
||||
(define-inline org-roam-buffer--visibility ()
|
||||
"Return the current visibility state of the persistent `org-roam-buffer'.
|
||||
"Return whether the current visibility state of the org-roam buffer.
|
||||
Valid states are 'visible, 'exists and 'none."
|
||||
(declare (side-effect-free t))
|
||||
(inline-quote
|
||||
@@ -280,205 +212,44 @@ Valid states are 'visible, 'exists and 'none."
|
||||
((get-buffer org-roam-buffer) 'exists)
|
||||
(t 'none))))
|
||||
|
||||
(defun org-roam-buffer-toggle ()
|
||||
"Toggle display of the Org-roam buffer."
|
||||
(interactive)
|
||||
(pcase (org-roam-buffer--visibility)
|
||||
('visible
|
||||
(progn
|
||||
(delete-window (get-buffer-window org-roam-buffer))
|
||||
(remove-hook 'post-command-hook #'org-roam-buffer--post-command-h)))
|
||||
((or 'exists 'none)
|
||||
(progn
|
||||
(setq org-roam-current-node (org-roam-node-at-point)
|
||||
org-roam-current-directory org-roam-directory)
|
||||
(display-buffer (get-buffer-create org-roam-buffer))
|
||||
(org-roam-buffer-persistent-redisplay)))))
|
||||
|
||||
(defun org-roam-buffer-persistent-redisplay ()
|
||||
"Recompute contents of the persistent `org-roam-buffer'.
|
||||
Has no effect when there's no `org-roam-node-at-point'."
|
||||
(when-let ((node (org-roam-node-at-point)))
|
||||
(unless (equal node org-roam-buffer-current-node)
|
||||
(setq org-roam-buffer-current-node node
|
||||
org-roam-buffer-current-directory org-roam-directory)
|
||||
(with-current-buffer (get-buffer-create org-roam-buffer)
|
||||
(org-roam-buffer-render-contents)
|
||||
(add-hook 'kill-buffer-hook #'org-roam-buffer--persistent-cleanup-h nil t)))))
|
||||
"Recompute contents of the persistent Org-roam buffer.
|
||||
Has no effect when `org-roam-current-node' is nil."
|
||||
(when org-roam-current-node
|
||||
(with-current-buffer (get-buffer-create org-roam-buffer)
|
||||
(let ((inhibit-read-only t))
|
||||
(erase-buffer)
|
||||
(org-roam-mode)
|
||||
(setq-local default-directory org-roam-current-directory)
|
||||
(setq-local org-roam-directory org-roam-current-directory)
|
||||
(org-roam-set-header-line-format (org-roam-node-title org-roam-current-node))
|
||||
(magit-insert-section (org-roam)
|
||||
(magit-insert-heading)
|
||||
(dolist (fn org-roam-mode-section-functions)
|
||||
(funcall fn org-roam-current-node)))))))
|
||||
|
||||
(defun org-roam-buffer--persistent-cleanup-h ()
|
||||
"Clean-up global state thats dedicated for the persistent `org-roam-buffer'."
|
||||
(setq-default org-roam-buffer-current-node nil
|
||||
org-roam-buffer-current-directory nil))
|
||||
(defun org-roam-buffer--redisplay ()
|
||||
"."
|
||||
(add-hook 'post-command-hook #'org-roam-buffer--post-command-h nil t))
|
||||
|
||||
(add-hook 'org-roam-find-file-hook #'org-roam-buffer--setup-redisplay-h)
|
||||
(defun org-roam-buffer--setup-redisplay-h ()
|
||||
"Setup automatic redisplay of the persistent `org-roam-buffer'."
|
||||
(add-hook 'post-command-hook #'org-roam-buffer--redisplay-h nil t))
|
||||
|
||||
(defun org-roam-buffer--redisplay-h ()
|
||||
"Reconstruct the persistent `org-roam-buffer'.
|
||||
This needs to be quick or infrequent, because this designed to
|
||||
run at `post-command-hook'."
|
||||
(and (get-buffer-window org-roam-buffer)
|
||||
(org-roam-buffer-persistent-redisplay)))
|
||||
(add-hook 'org-roam-find-file-hook #'org-roam-buffer--redisplay)
|
||||
|
||||
;;; Sections
|
||||
;;;; Node
|
||||
(defvar org-roam-node-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(set-keymap-parent map org-roam-mode-map)
|
||||
(define-key map [remap org-roam-buffer-visit-thing] 'org-roam-node-visit)
|
||||
map)
|
||||
"Keymap for `org-roam-node-section's.")
|
||||
|
||||
(defclass org-roam-node-section (magit-section)
|
||||
((keymap :initform 'org-roam-node-map)
|
||||
(node :initform nil))
|
||||
"A `magit-section' used by `org-roam-mode' to outline NODE in its own heading.")
|
||||
|
||||
(cl-defun org-roam-node-insert-section (&key source-node point properties)
|
||||
"Insert section for a link from SOURCE-NODE to some other node.
|
||||
The other node is normally `org-roam-buffer-current-node'.
|
||||
|
||||
SOURCE-NODE is an `org-roam-node' that links or references with
|
||||
the other node.
|
||||
|
||||
POINT is a character position where the link is located in
|
||||
SOURCE-NODE's file.
|
||||
|
||||
PROPERTIES (a plist) contains additional information about the
|
||||
link.
|
||||
|
||||
Despite the name, this function actually inserts 2 sections at
|
||||
the same time:
|
||||
|
||||
1. `org-roam-node-section' for a heading that describes
|
||||
SOURCE-NODE. Acts as a parent section of the following one.
|
||||
|
||||
2. `org-roam-preview-section' for a preview content that comes
|
||||
from SOURCE-NODE's file for the link (that references the
|
||||
other node) at POINT. Acts a child section of the previous
|
||||
one."
|
||||
(magit-insert-section section (org-roam-node-section)
|
||||
(let ((outline (if-let ((outline (plist-get properties :outline)))
|
||||
(mapconcat #'org-link-display-format outline " > ")
|
||||
"Top")))
|
||||
(insert (concat (propertize (org-roam-node-title source-node)
|
||||
'font-lock-face 'org-roam-title)
|
||||
(format " (%s)"
|
||||
(propertize outline 'font-lock-face 'org-roam-olp)))))
|
||||
(magit-insert-heading)
|
||||
(oset section node source-node)
|
||||
(magit-insert-section section (org-roam-preview-section)
|
||||
(insert (org-roam-fontify-like-in-org-mode
|
||||
(org-roam-preview-get-contents (org-roam-node-file source-node) point))
|
||||
"\n")
|
||||
(oset section file (org-roam-node-file source-node))
|
||||
(oset section point point)
|
||||
(insert ?\n))))
|
||||
|
||||
;;;; Preview
|
||||
(defvar org-roam-preview-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(set-keymap-parent map org-roam-mode-map)
|
||||
(define-key map [remap org-roam-buffer-visit-thing] 'org-roam-preview-visit)
|
||||
map)
|
||||
"Keymap for `org-roam-preview-section's.")
|
||||
|
||||
(defclass org-roam-preview-section (magit-section)
|
||||
((keymap :initform 'org-roam-preview-map)
|
||||
(file :initform nil)
|
||||
(point :initform nil))
|
||||
"A `magit-section' used by `org-roam-mode' to contain preview content.
|
||||
The preview content comes from FILE, and the link as at POINT.")
|
||||
|
||||
(defun org-roam-preview-visit (file point &optional other-window)
|
||||
"Visit FILE at POINT and return the visited buffer.
|
||||
With OTHER-WINDOW non-nil do so in another window.
|
||||
In interactive calls OTHER-WINDOW is set with
|
||||
`universal-argument'."
|
||||
(interactive (list (org-roam-buffer-file-at-point 'assert)
|
||||
(oref (magit-current-section) point)
|
||||
current-prefix-arg))
|
||||
(let ((buf (find-file-noselect file))
|
||||
(display-buffer-fn (if other-window
|
||||
#'switch-to-buffer-other-window
|
||||
#'pop-to-buffer-same-window)))
|
||||
(funcall display-buffer-fn buf)
|
||||
(with-current-buffer buf
|
||||
(widen)
|
||||
(goto-char point))
|
||||
(when (org-invisible-p) (org-show-context))
|
||||
buf))
|
||||
|
||||
(defun org-roam-preview-get-contents (file point)
|
||||
"Get preview content for FILE at POINT."
|
||||
(save-excursion
|
||||
(org-roam-with-temp-buffer file
|
||||
(goto-char point)
|
||||
(let ((elem (org-element-at-point)))
|
||||
;; We want the parent element always
|
||||
(while (org-element-property :parent elem)
|
||||
(setq elem (org-element-property :parent elem)))
|
||||
(pcase (car elem)
|
||||
('headline ; show subtree
|
||||
(org-roam-preview-get-entry-text (point-marker) most-positive-fixnum))
|
||||
(_
|
||||
(let ((begin (org-element-property :begin elem))
|
||||
(end (org-element-property :end elem)))
|
||||
(or (string-trim (buffer-substring-no-properties begin end))
|
||||
(org-element-property :raw-value elem)))))))))
|
||||
|
||||
(defun org-roam-preview-get-entry-text (marker n-lines &optional indent)
|
||||
"Extract entry text from MARKER, at most N-LINES lines.
|
||||
This will ignore drawers etc, just get the text.
|
||||
If INDENT is given, prefix every line with this string."
|
||||
(let (txt ind)
|
||||
(save-excursion
|
||||
(with-current-buffer (marker-buffer marker)
|
||||
(if (not (derived-mode-p 'org-mode))
|
||||
(setq txt "")
|
||||
(org-with-wide-buffer
|
||||
(goto-char marker)
|
||||
(end-of-line 1)
|
||||
(setq txt (buffer-substring
|
||||
(min (1+ (point)) (point-max))
|
||||
(progn (outline-next-heading) (point))))
|
||||
(with-temp-buffer
|
||||
(insert txt)
|
||||
(goto-char (point-min))
|
||||
(while (org-activate-links (point-max))
|
||||
(goto-char (match-end 0)))
|
||||
(goto-char (point-min))
|
||||
(while (re-search-forward org-link-bracket-re (point-max) t)
|
||||
(set-text-properties (match-beginning 0) (match-end 0)
|
||||
nil))
|
||||
(goto-char (point-min))
|
||||
(while (re-search-forward org-drawer-regexp nil t)
|
||||
(delete-region
|
||||
(match-beginning 0)
|
||||
(progn (re-search-forward
|
||||
"^[ \t]*:END:.*\n?" nil 'move)
|
||||
(point))))
|
||||
(goto-char (point-min))
|
||||
(goto-char (point-max))
|
||||
(skip-chars-backward " \t\n")
|
||||
(when (looking-at "[ \t\n]+\\'") (replace-match ""))
|
||||
|
||||
;; find and remove min common indentation
|
||||
(goto-char (point-min))
|
||||
(untabify (point-min) (point-max))
|
||||
(setq ind (current-indentation))
|
||||
(while (not (eobp))
|
||||
(unless (looking-at "[ \t]*$")
|
||||
(setq ind (min ind (current-indentation))))
|
||||
(beginning-of-line 2))
|
||||
(goto-char (point-min))
|
||||
(while (not (eobp))
|
||||
(unless (looking-at "[ \t]*$")
|
||||
(move-to-column ind)
|
||||
(delete-region (point-at-bol) (point)))
|
||||
(beginning-of-line 2))
|
||||
(goto-char (point-min))
|
||||
(when indent
|
||||
(while (and (not (eobp)) (re-search-forward "^" nil t))
|
||||
(replace-match indent t t)))
|
||||
(goto-char (point-min))
|
||||
(while (looking-at "[ \t]*\n") (replace-match ""))
|
||||
(goto-char (point-max))
|
||||
(when (> (org-current-line)
|
||||
n-lines)
|
||||
(org-goto-line (1+ n-lines))
|
||||
(backward-char 1))
|
||||
(setq txt (buffer-substring (point-min) (point))))))))
|
||||
txt))
|
||||
|
||||
;;;; Backlinks
|
||||
(cl-defstruct (org-roam-backlink (:constructor org-roam-backlink-create)
|
||||
(:copier nil))
|
||||
@@ -579,11 +350,11 @@ Sorts by title."
|
||||
:properties (org-roam-reflink-properties reflink)))
|
||||
(insert ?\n)))))
|
||||
|
||||
;;;; Grep
|
||||
;;;; Unlinked references
|
||||
(defvar org-roam-grep-map
|
||||
(let ((map (make-sparse-keymap)))
|
||||
(set-keymap-parent map org-roam-mode-map)
|
||||
(define-key map [remap org-roam-buffer-visit-thing] 'org-roam-grep-visit)
|
||||
(define-key map [remap org-roam-visit-thing] 'org-roam-file-visit)
|
||||
map)
|
||||
"Keymap for Org-roam grep result sections.")
|
||||
|
||||
@@ -591,23 +362,29 @@ Sorts by title."
|
||||
((keymap :initform 'org-roam-grep-map)
|
||||
(file :initform nil)
|
||||
(row :initform nil)
|
||||
(col :initform nil))
|
||||
"A `magit-section' used by `org-roam-mode' to contain grep output.")
|
||||
(col :initform nil)))
|
||||
|
||||
(defun org-roam-grep-visit (file &optional other-window row col)
|
||||
"Visit FILE at row ROW (if any) and column COL (if any). Return the buffer.
|
||||
With OTHER-WINDOW non-nil (in interactive calls set with
|
||||
`universal-argument') display the buffer in another window
|
||||
instead."
|
||||
(interactive (list (org-roam-buffer-file-at-point t)
|
||||
(defun org-roam-file-at-point (&optional assert)
|
||||
"Return the file at point.
|
||||
If ASSERT, throw an error."
|
||||
(if-let ((file (magit-section-case
|
||||
(org-roam-node-section (org-roam-node-file (oref it node)))
|
||||
(org-roam-grep-section (oref it file))
|
||||
(org-roam-preview-section (oref it file)))))
|
||||
file
|
||||
(when assert
|
||||
(user-error "No file at point"))))
|
||||
|
||||
(defun org-roam-file-visit (file &optional other-window row col)
|
||||
"Visits FILE.
|
||||
With a prefix argument OTHER-WINDOW, display the buffer in
|
||||
another window instead.
|
||||
If ROW, move to the row, and if COL move to the COL."
|
||||
(interactive (list (org-roam-file-at-point t)
|
||||
current-prefix-arg
|
||||
(oref (magit-current-section) row)
|
||||
(oref (magit-current-section) col)))
|
||||
(let ((buf (find-file-noselect file))
|
||||
(display-buffer-fn (if other-window
|
||||
#'switch-to-buffer-other-window
|
||||
#'pop-to-buffer-same-window)))
|
||||
(funcall display-buffer-fn buf)
|
||||
(let ((buf (find-file-noselect file)))
|
||||
(with-current-buffer buf
|
||||
(widen)
|
||||
(goto-char (point-min))
|
||||
@@ -615,10 +392,10 @@ instead."
|
||||
(forward-line (1- row)))
|
||||
(when col
|
||||
(forward-char (1- col))))
|
||||
(when (org-invisible-p) (org-show-context))
|
||||
buf))
|
||||
(funcall (if other-window
|
||||
#'switch-to-buffer-other-window
|
||||
#'pop-to-buffer-same-window) buf)))
|
||||
|
||||
;;;; Unlinked references
|
||||
(defvar org-roam-unlinked-references-result-re
|
||||
(rx (group (one-or-more anything))
|
||||
":"
|
||||
@@ -633,7 +410,7 @@ instead."
|
||||
"Return the preview line from FILE.
|
||||
This is the ROW within FILE."
|
||||
(with-temp-buffer
|
||||
(insert-file-contents file)
|
||||
(insert-file-contents-literally file)
|
||||
(forward-line (1- row))
|
||||
(buffer-substring-no-properties
|
||||
(save-excursion
|
||||
|
||||
1049
org-roam-node.el
1049
org-roam-node.el
File diff suppressed because it is too large
Load Diff
@@ -1,12 +1,12 @@
|
||||
;;; org-roam-overlay.el --- Link overlay for [id:] links to Org-roam nodes -*- coding: utf-8; lexical-binding: t; -*-
|
||||
;;; org-roam-overlay.el --- Link overlay for Org-roam nodes -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.1"))
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
@@ -27,11 +27,13 @@
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This extension provides allows to render [[id:]] links that don't have an
|
||||
;; asscoiated descriptor with an overlay that displays the node's current title.
|
||||
;; This library is an attempt at injecting Roam functionality into Org-mode.
|
||||
;; This is achieved primarily through building caches for forward links,
|
||||
;; backward links, and file titles.
|
||||
;;
|
||||
;;
|
||||
;;; Code:
|
||||
(require 'org-roam)
|
||||
;;;; Dependencies
|
||||
|
||||
(defface org-roam-overlay
|
||||
'((((class color) (background light))
|
||||
107
org-roam-protocol.el
Normal file
107
org-roam-protocol.el
Normal file
@@ -0,0 +1,107 @@
|
||||
;;; org-roam-protocol.el --- Protocol handler for roam:// links -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
;; This program is free software; you can redistribute it and/or modify
|
||||
;; it under the terms of the GNU General Public License as published by
|
||||
;; the Free Software Foundation; either version 3, or (at your option)
|
||||
;; any later version.
|
||||
;;
|
||||
;; This program is distributed in the hope that it will be useful,
|
||||
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
;; GNU General Public License for more details.
|
||||
;;
|
||||
;; You should have received a copy of the GNU General Public License
|
||||
;; along with GNU Emacs; see the file COPYING. If not, write to the
|
||||
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
||||
;; Boston, MA 02110-1301, USA.
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; We extend org-protocol, adding custom Org-roam handlers. The setup
|
||||
;; instructions for `org-protocol' can be found in org-protocol.el.
|
||||
;;
|
||||
;; We define 2 protocols:
|
||||
;;
|
||||
;; 1. "roam-node": This protocol simply opens the node given by the node ID
|
||||
;; 2. "roam-ref": This protocol creates or opens a note with the given REF
|
||||
;;
|
||||
;;; Code:
|
||||
(require 'org-protocol)
|
||||
(require 'org-roam)
|
||||
(eval-when-compile
|
||||
(require 'org-roam-macs))
|
||||
(require 'ol) ;; for org-link-decode
|
||||
|
||||
(defcustom org-roam-protocol-store-links nil
|
||||
"Whether to store links when capturing websites with `org-roam-protocol'."
|
||||
:type 'boolean
|
||||
:group 'org-roam)
|
||||
|
||||
;;;; Functions
|
||||
(defun org-roam-protocol-open-ref (info)
|
||||
"Process an org-protocol://roam-ref?ref= style url with INFO.
|
||||
|
||||
It opens or creates a note with the given ref.
|
||||
|
||||
javascript:location.href = \\='org-protocol://roam-ref?template=r&ref=\\='+ \\
|
||||
encodeURIComponent(location.href) + \\='&title=\\=' + \\
|
||||
encodeURIComponent(document.title) + \\='&body=\\=' + \\
|
||||
encodeURIComponent(window.getSelection())"
|
||||
(unless (plist-get info :ref)
|
||||
(user-error "No ref key provided"))
|
||||
(org-roam-plist-map! (lambda (k v)
|
||||
(org-link-decode
|
||||
(if (equal k :ref)
|
||||
(org-protocol-sanitize-uri v)
|
||||
v))) info)
|
||||
(when org-roam-protocol-store-links
|
||||
(push (list (plist-get info :ref)
|
||||
(plist-get info :title)) org-stored-links))
|
||||
(org-link-store-props :type (and (string-match org-link-plain-re
|
||||
(plist-get info :ref))
|
||||
(match-string 1 (plist-get info :ref)))
|
||||
:link (plist-get info :ref)
|
||||
:annotation (org-link-make-string (plist-get info :ref)
|
||||
(or (plist-get info :title)
|
||||
(plist-get info :ref)))
|
||||
:initial (or (plist-get info :body) ""))
|
||||
(raise-frame)
|
||||
(org-roam-capture-
|
||||
:keys (plist-get info :template)
|
||||
:node (org-roam-node-create :title (plist-get info :title))
|
||||
:info (list :ref (plist-get info :ref)
|
||||
:body (plist-get info :body))
|
||||
:templates org-roam-capture-ref-templates)
|
||||
nil)
|
||||
|
||||
(defun org-roam-protocol-open-node (info)
|
||||
"This handler simply opens the file with emacsclient.
|
||||
|
||||
INFO is an alist containing additional information passed by the protocol URL.
|
||||
It should contain the FILE key, pointing to the path of the file to open.
|
||||
|
||||
Example protocol string:
|
||||
|
||||
org-protocol://roam-node?node=uuid"
|
||||
(when-let ((node (plist-get info :node)))
|
||||
(raise-frame)
|
||||
(org-roam-node-visit (org-roam-populate (org-roam-node-create :id node))))
|
||||
nil)
|
||||
|
||||
(push '("org-roam-ref" :protocol "roam-ref" :function org-roam-protocol-open-ref)
|
||||
org-protocol-protocol-alist)
|
||||
(push '("org-roam-node" :protocol "roam-node" :function org-roam-protocol-open-node)
|
||||
org-protocol-protocol-alist)
|
||||
|
||||
(provide 'org-roam-protocol)
|
||||
|
||||
;;; org-roam-protocol.el ends here
|
||||
@@ -1,12 +1,12 @@
|
||||
;;; org-roam-utils.el --- Utilities for Org-roam -*- lexical-binding: t; -*-
|
||||
;;; org-roam-utils.el --- Utilities for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
|
||||
|
||||
;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||||
|
||||
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
|
||||
;; URL: https://github.com/org-roam/org-roam
|
||||
;; Keywords: org-mode, roam, convenience
|
||||
;; Version: 2.1.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.4"))
|
||||
;; Version: 2.0.0
|
||||
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1"))
|
||||
|
||||
;; This file is NOT part of GNU Emacs.
|
||||
|
||||
@@ -27,14 +27,41 @@
|
||||
|
||||
;;; Commentary:
|
||||
;;
|
||||
;; This library provides definitions for utilities that used throughout the
|
||||
;; whole package.
|
||||
;; This library implements utility functions used throughout
|
||||
;; Org-roam.
|
||||
;;
|
||||
;;
|
||||
;;; Code:
|
||||
;;;; Library Requires
|
||||
(require 'dash)
|
||||
|
||||
;;; String utilities
|
||||
;; TODO Refactor this.
|
||||
(defun org-roam-replace-string (old new s)
|
||||
(eval-when-compile
|
||||
(require 'org-roam-macs)
|
||||
(require 'org-macs))
|
||||
|
||||
(defvar org-roam-verbose)
|
||||
|
||||
;; This is necessary to ensure all dependents on this module see
|
||||
;; `org-mode-hook' and `org-inhibit-startup' as dynamic variables,
|
||||
;; regardless of whether Org is loaded before their compilation.
|
||||
(require 'org)
|
||||
|
||||
;;;; String Utilities
|
||||
(defun org-roam-truncate (len s &optional ellipsis)
|
||||
"If S is longer than LEN, cut it down and add ELLIPSIS to the end.
|
||||
|
||||
The resulting string, including ellipsis, will be LEN characters
|
||||
long.
|
||||
|
||||
When not specified, ELLIPSIS defaults to ‘...’."
|
||||
(declare (pure t) (side-effect-free t))
|
||||
(unless ellipsis
|
||||
(setq ellipsis "..."))
|
||||
(if (> (length s) len)
|
||||
(format "%s%s" (substring s 0 (- len (length ellipsis))) ellipsis)
|
||||
s))
|
||||
|
||||
(defun org-roam-replace (old new s)
|
||||
"Replace OLD with NEW in S."
|
||||
(declare (pure t) (side-effect-free t))
|
||||
(replace-regexp-in-string (regexp-quote old) new s t t))
|
||||
@@ -42,97 +69,36 @@
|
||||
(defun org-roam-quote-string (s)
|
||||
"Quotes string S."
|
||||
(->> s
|
||||
(org-roam-replace-string "\\" "\\\\")
|
||||
(org-roam-replace-string "\"" "\\\"")))
|
||||
(org-roam-replace "\\" "\\\\")
|
||||
(org-roam-replace "\"" "\\\"")))
|
||||
|
||||
;;; List utilities
|
||||
(defmacro org-roam-plist-map! (fn plist)
|
||||
"Map FN over PLIST, modifying it in-place."
|
||||
(declare (indent 1))
|
||||
(let ((plist-var (make-symbol "plist"))
|
||||
(k (make-symbol "k"))
|
||||
(v (make-symbol "v")))
|
||||
`(let ((,plist-var (copy-sequence ,plist)))
|
||||
(while ,plist-var
|
||||
(setq ,k (pop ,plist-var))
|
||||
(setq ,v (pop ,plist-var))
|
||||
(setq ,plist (plist-put ,plist ,k (funcall ,fn ,k ,v)))))))
|
||||
;;;; Utility Functions
|
||||
(defun org-roam--list-interleave (lst separator)
|
||||
"Interleaves elements in LST with SEPARATOR."
|
||||
(when lst
|
||||
(let ((new-lst (list (pop lst))))
|
||||
(dolist (it lst)
|
||||
(nconc new-lst (list separator it)))
|
||||
new-lst)))
|
||||
|
||||
;;; File utilities
|
||||
(defmacro org-roam-with-file (file keep-buf-p &rest body)
|
||||
"Execute BODY within FILE.
|
||||
If FILE is nil, execute BODY in the current buffer.
|
||||
Kills the buffer if KEEP-BUF-P is nil, and FILE is not yet visited."
|
||||
(declare (indent 2) (debug t))
|
||||
`(let* (new-buf
|
||||
(auto-mode-alist nil)
|
||||
(buf (or (and (not ,file)
|
||||
(current-buffer)) ;If FILE is nil, use current buffer
|
||||
(find-buffer-visiting ,file) ; If FILE is already visited, find buffer
|
||||
(progn
|
||||
(setq new-buf t)
|
||||
(find-file-noselect ,file)))) ; Else, visit FILE and return buffer
|
||||
res)
|
||||
(with-current-buffer buf
|
||||
(unless (equal major-mode 'org-mode)
|
||||
(delay-mode-hooks
|
||||
(let ((org-inhibit-startup t)
|
||||
(org-agenda-files nil))
|
||||
(org-mode))))
|
||||
(setq res (progn ,@body))
|
||||
(unless (and new-buf (not ,keep-buf-p))
|
||||
(save-buffer)))
|
||||
(if (and new-buf (not ,keep-buf-p))
|
||||
(when (find-buffer-visiting ,file)
|
||||
(kill-buffer (find-buffer-visiting ,file))))
|
||||
res))
|
||||
(defun org-roam-up-heading-or-point-min ()
|
||||
"Fixed version of Org's `org-up-heading-or-point-min'."
|
||||
(ignore-errors (org-back-to-heading t))
|
||||
(let ((p (point)))
|
||||
(if (< 1 (funcall outline-level))
|
||||
(progn
|
||||
(org-up-heading-safe)
|
||||
(when (= (point) p)
|
||||
(goto-char (point-min))))
|
||||
(unless (bobp) (goto-char (point-min))))))
|
||||
|
||||
;;; Buffer utilities
|
||||
(defmacro org-roam-with-temp-buffer (file &rest body)
|
||||
"Execute BODY within a temp buffer.
|
||||
Like `with-temp-buffer', but propagates `org-roam-directory'.
|
||||
If FILE, set `default-directory' to FILE's directory and insert its contents."
|
||||
(declare (indent 1) (debug t))
|
||||
(let ((current-org-roam-directory (make-symbol "current-org-roam-directory")))
|
||||
`(let ((,current-org-roam-directory org-roam-directory))
|
||||
(with-temp-buffer
|
||||
(let ((org-roam-directory ,current-org-roam-directory))
|
||||
(delay-mode-hooks (org-mode))
|
||||
(when ,file
|
||||
(insert-file-contents ,file)
|
||||
(setq-local default-directory (file-name-directory ,file)))
|
||||
,@body)))))
|
||||
(defun org-roam-message (format-string &rest args)
|
||||
"Pass FORMAT-STRING and ARGS to `message' when `org-roam-verbose' is t."
|
||||
(when org-roam-verbose
|
||||
(apply #'message `(,(concat "(org-roam) " format-string) ,@args))))
|
||||
|
||||
;;; Formatting
|
||||
(defun org-roam-format-template (template replacer)
|
||||
"Format TEMPLATE with the function REPLACER.
|
||||
The templates are of form ${foo} for variable foo, and
|
||||
${foo=default} for variable foo with default value \"default\".
|
||||
REPLACER takes an argument of the format variable and the default
|
||||
value (possibly nil). Adapted from `s-format'."
|
||||
(let ((saved-match-data (match-data)))
|
||||
(unwind-protect
|
||||
(replace-regexp-in-string
|
||||
"\\${\\([^}]+\\)}"
|
||||
(lambda (md)
|
||||
(let ((var (match-string 1 md))
|
||||
(replacer-match-data (match-data))
|
||||
default-val)
|
||||
(when (string-match "\\(.+\\)=\\(.+\\)" var)
|
||||
(setq default-val (match-string 2 var)
|
||||
var (match-string 1 var)))
|
||||
(unwind-protect
|
||||
(let ((v (progn
|
||||
(set-match-data saved-match-data)
|
||||
(funcall replacer var default-val))))
|
||||
(if v (format "%s" v) (signal 'org-roam-format-resolve md)))
|
||||
(set-match-data replacer-match-data))))
|
||||
template
|
||||
;; Need literal to make sure it works
|
||||
t t)
|
||||
(set-match-data saved-match-data))))
|
||||
(defvar org-ref-buffer-hacked)
|
||||
|
||||
;;; Fontification
|
||||
(defun org-roam-fontify-like-in-org-mode (s)
|
||||
"Fontify string S like in Org mode.
|
||||
Like `org-fontify-like-in-org-mode', but supports `org-ref'."
|
||||
@@ -159,7 +125,38 @@ Like `org-fontify-like-in-org-mode', but supports `org-ref'."
|
||||
(org-font-lock-ensure)
|
||||
(buffer-string))))
|
||||
|
||||
;;;; Shielding regions
|
||||
(defun org-roam-set-header-line-format (string)
|
||||
"Set the header-line using STRING.
|
||||
If the `face' property of any part of STRING is already set, then
|
||||
that takes precedence. Also pad the left side of STRING so that
|
||||
it aligns with the text area."
|
||||
(setq-local header-line-format
|
||||
(concat (propertize " " 'display '(space :align-to 0))
|
||||
string)))
|
||||
|
||||
;;; Keywords
|
||||
(defun org-roam--get-keyword (name &optional bound)
|
||||
"Return keyword property NAME in current buffer.
|
||||
If BOUND, scan up to BOUND bytes of the buffer."
|
||||
(save-excursion
|
||||
(let ((re (format "^#\\+%s:[ \t]*\\([^\n]+\\)" (upcase name))))
|
||||
(goto-char (point-min))
|
||||
(when (re-search-forward re bound t)
|
||||
(buffer-substring-no-properties (match-beginning 1) (match-end 1))))))
|
||||
|
||||
(defun org-roam-get-keyword (name &optional file bound)
|
||||
"Return keyword property NAME from an org FILE.
|
||||
FILE defaults to current file.
|
||||
Only scans up to BOUND bytes of the document."
|
||||
(unless bound
|
||||
(setq bound 1024))
|
||||
(if file
|
||||
(with-temp-buffer
|
||||
(insert-file-contents-literally file nil 0 bound)
|
||||
(org-roam--get-keyword name))
|
||||
(org-roam--get-keyword name bound)))
|
||||
|
||||
;;; Shielding regions
|
||||
(defface org-roam-shielded
|
||||
'((t :inherit (warning)))
|
||||
"Face for regions that are shielded (marked as read-only).
|
||||
@@ -186,62 +183,59 @@ BEG and END are markers for the beginning and end regions."
|
||||
read-only t)
|
||||
(marker-buffer beg))))
|
||||
|
||||
;;; Org-mode utilities
|
||||
;;;; Motions
|
||||
(defun org-roam-up-heading-or-point-min ()
|
||||
"Fixed version of Org's `org-up-heading-or-point-min'."
|
||||
(ignore-errors (org-back-to-heading t))
|
||||
(let ((p (point)))
|
||||
(if (< 1 (funcall outline-level))
|
||||
(progn
|
||||
(org-up-heading-safe)
|
||||
(when (= (point) p)
|
||||
(goto-char (point-min))))
|
||||
(unless (bobp) (goto-char (point-min))))))
|
||||
;;; Formatting
|
||||
(defun org-roam-format (template replacer)
|
||||
"Format TEMPLATE with the function REPLACER.
|
||||
REPLACER takes an argument of the format variable and optionally
|
||||
an extra argument which is the EXTRA value from the call to
|
||||
`org-roam-format'.
|
||||
Adapted from `s-format'."
|
||||
(let ((saved-match-data (match-data)))
|
||||
(unwind-protect
|
||||
(replace-regexp-in-string
|
||||
"\\${\\([^}]+\\)}"
|
||||
(lambda (md)
|
||||
(let ((var (match-string 1 md))
|
||||
(replacer-match-data (match-data)))
|
||||
(unwind-protect
|
||||
(let ((v (progn
|
||||
(set-match-data saved-match-data)
|
||||
(funcall replacer var))))
|
||||
(if v (format "%s" v) (signal 'org-roam-format-resolve md)))
|
||||
(set-match-data replacer-match-data)))) template
|
||||
;; Need literal to make sure it works
|
||||
t t)
|
||||
(set-match-data saved-match-data))))
|
||||
|
||||
;;;; Keywords
|
||||
(defun org-roam-get-keyword (name &optional file bound)
|
||||
"Return keyword property NAME from an org FILE.
|
||||
FILE defaults to current file.
|
||||
Only scans up to BOUND bytes of the document."
|
||||
(unless bound
|
||||
(setq bound 1024))
|
||||
(if file
|
||||
(with-temp-buffer
|
||||
(insert-file-contents file nil 0 bound)
|
||||
(org-roam--get-keyword name))
|
||||
(org-roam--get-keyword name bound)))
|
||||
(defvar org-roam--cached-display-format nil)
|
||||
|
||||
(defun org-roam--get-keyword (name &optional bound)
|
||||
"Return keyword property NAME in current buffer.
|
||||
If BOUND, scan up to BOUND bytes of the buffer."
|
||||
(save-excursion
|
||||
(let ((re (format "^#\\+%s:[ \t]*\\([^\n]+\\)" (upcase name))))
|
||||
(goto-char (point-min))
|
||||
(when (re-search-forward re bound t)
|
||||
(buffer-substring-no-properties (match-beginning 1) (match-end 1))))))
|
||||
(defun org-roam--process-display-format (format)
|
||||
"Pre-calculate minimal widths needed by the FORMAT string."
|
||||
(or org-roam--cached-display-format
|
||||
(setq org-roam--cached-display-format
|
||||
(let* ((fields-width 0)
|
||||
(string-width
|
||||
(string-width
|
||||
(org-roam-format
|
||||
format
|
||||
(lambda (field)
|
||||
(setq fields-width
|
||||
(+ fields-width
|
||||
(string-to-number
|
||||
(or (cadr (split-string field ":"))
|
||||
"")))))))))
|
||||
(cons format (+ fields-width string-width))))))
|
||||
|
||||
(defun org-roam-set-keyword (key value)
|
||||
"Set keyword KEY to VALUE.
|
||||
If the property is already set, it's value is replaced."
|
||||
(org-with-point-at 1
|
||||
(let ((case-fold-search t))
|
||||
(if (re-search-forward (concat "^#\\+" key ":\\(.*\\)") (point-max) t)
|
||||
(if (string-blank-p value)
|
||||
(kill-whole-line)
|
||||
(replace-match (concat " " value) 'fixedcase nil nil 1))
|
||||
(while (and (not (eobp))
|
||||
(looking-at "^[#:]"))
|
||||
(if (save-excursion (end-of-line) (eobp))
|
||||
(progn
|
||||
(end-of-line)
|
||||
(insert "\n"))
|
||||
(forward-line)
|
||||
(beginning-of-line)))
|
||||
(insert "#+" key ": " value "\n")))))
|
||||
;;; for org-roam-demote-entire-buffer in org-roam-refile.el
|
||||
(defun org-roam--file-keyword-get (keyword)
|
||||
"Pull a KEYWORD setting from the top of the file.
|
||||
|
||||
(defun org-roam-erase-keyword (keyword)
|
||||
"Erase the line where the KEYWORD is, setting line from the top of the file."
|
||||
Keyword must be specified in ALL CAPS."
|
||||
(cadr (assoc keyword
|
||||
(org-collect-keywords (list keyword)))))
|
||||
|
||||
(defun org-roam--file-keyword-kill (keyword)
|
||||
"Erase KEYWORD setting line from the top of the file."
|
||||
(let ((case-fold-search t))
|
||||
(org-with-point-at 1
|
||||
(when (re-search-forward (concat "^#\\+" keyword ":") nil t)
|
||||
@@ -249,84 +243,39 @@ If the property is already set, it's value is replaced."
|
||||
(delete-region (point) (line-end-position))
|
||||
(delete-char 1)))))
|
||||
|
||||
;;;; Properties
|
||||
(defun org-roam-add-property (val prop)
|
||||
"Add VAL value to PROP property for the node at point.
|
||||
Both, VAL and PROP are strings."
|
||||
(let* ((p (org-entry-get (point) prop))
|
||||
(lst (when p (split-string-and-unquote p)))
|
||||
(lst (if (memq val lst) lst (cons val lst)))
|
||||
(lst (seq-uniq lst)))
|
||||
(org-set-property prop (combine-and-quote-strings lst))
|
||||
val))
|
||||
(defun org-roam--kill-empty-buffer ()
|
||||
"If the source buffer has been emptied, kill it.
|
||||
|
||||
(defun org-roam-remove-property (prop &optional val)
|
||||
"Remove VAL value from PROP property for the node at point.
|
||||
Both VAL and PROP are strings.
|
||||
If the buffer is associated with a file, delete the file.
|
||||
|
||||
If VAL is not specified, user is prompted to select a value."
|
||||
(let* ((p (org-entry-get (point) prop))
|
||||
(lst (when p (split-string-and-unquote p)))
|
||||
(prop-to-remove (or val (completing-read "Remove: " lst)))
|
||||
(lst (delete prop-to-remove lst)))
|
||||
(if lst
|
||||
(org-set-property prop (combine-and-quote-strings lst))
|
||||
(org-delete-property prop))
|
||||
prop-to-remove))
|
||||
|
||||
;;; Logs
|
||||
(defvar org-roam-verbose)
|
||||
(defun org-roam-message (format-string &rest args)
|
||||
"Pass FORMAT-STRING and ARGS to `message' when `org-roam-verbose' is t."
|
||||
(when org-roam-verbose
|
||||
(apply #'message `(,(concat "(org-roam) " format-string) ,@args))))
|
||||
If the buffer is associated with an in-process capture operation, abort the operation."
|
||||
(when (eq (buffer-size) 0)
|
||||
(if (buffer-file-name)
|
||||
(delete-file (buffer-file-name)))
|
||||
(set-buffer-modified-p nil)
|
||||
(when (and org-capture-mode
|
||||
(buffer-base-buffer (current-buffer)))
|
||||
(org-capture-kill))
|
||||
(kill-buffer (current-buffer))))
|
||||
|
||||
;;; Diagnostics
|
||||
;; TODO Update this to also get commit hash
|
||||
;;;###autoload
|
||||
(defun org-roam-version (&optional message)
|
||||
"Return `org-roam' version.
|
||||
Interactively, or when MESSAGE is non-nil, show in the echo area."
|
||||
(interactive)
|
||||
(let* ((toplib (or load-file-name buffer-file-name))
|
||||
gitdir topdir version)
|
||||
(unless (and toplib (equal (file-name-nondirectory toplib) "org-roam-utils.el"))
|
||||
(setq toplib (locate-library "org-roam-utils.el")))
|
||||
(setq toplib (and toplib (org-roam--straight-chase-links toplib)))
|
||||
(when toplib
|
||||
(setq topdir (file-name-directory toplib)
|
||||
gitdir (expand-file-name ".git" topdir)))
|
||||
(when (file-exists-p gitdir)
|
||||
(setq version
|
||||
(let ((default-directory topdir))
|
||||
(shell-command-to-string "git describe --tags --dirty --always"))))
|
||||
(unless version
|
||||
(setq version (with-temp-buffer
|
||||
(insert-file-contents-literally (locate-library "org-roam.el"))
|
||||
(goto-char (point-min))
|
||||
(save-match-data
|
||||
(if (re-search-forward "\\(?:;; Version: \\([^z-a]*?$\\)\\)" nil nil)
|
||||
(substring-no-properties (match-string 1))
|
||||
"N/A")))))
|
||||
(let* ((version
|
||||
(with-temp-buffer
|
||||
(insert-file-contents-literally (locate-library "org-roam.el"))
|
||||
(goto-char (point-min))
|
||||
(save-match-data
|
||||
(if (re-search-forward "\\(?:;; Version: \\([^z-a]*?$\\)\\)" nil nil)
|
||||
(substring-no-properties (match-string 1))
|
||||
"N/A")))))
|
||||
(if (or message (called-interactively-p 'interactive))
|
||||
(message "%s" version)
|
||||
version)))
|
||||
|
||||
(defun org-roam--straight-chase-links (filename)
|
||||
"Chase links in FILENAME until a name that is not a link.
|
||||
|
||||
This is the same as `file-chase-links', except that it also
|
||||
handles fake symlinks that are created by the package manager
|
||||
straight.el on Windows.
|
||||
|
||||
See <https://github.com/raxod502/straight.el/issues/520>."
|
||||
(when (and (bound-and-true-p straight-symlink-emulation-mode)
|
||||
(fboundp 'straight-chase-emulated-symlink))
|
||||
(when-let ((target (straight-chase-emulated-symlink filename)))
|
||||
(unless (eq target 'broken)
|
||||
(setq filename target))))
|
||||
(file-chase-links filename))
|
||||
|
||||
;;;###autoload
|
||||
(defun org-roam-diagnostics ()
|
||||
"Collect and print info for `org-roam' issues."
|
||||
@@ -343,6 +292,5 @@ See <https://github.com/raxod502/straight.el/issues/520>."
|
||||
(insert (format "- Org: %s\n" (org-version nil 'full)))
|
||||
(insert (format "- Org-roam: %s" (org-roam-version)))))
|
||||
|
||||
|
||||
(provide 'org-roam-utils)
|
||||
;;; org-roam-utils.el ends here
|
||||
|
||||
1247
org-roam.el
1247
org-roam.el
File diff suppressed because it is too large
Load Diff
@@ -1,7 +0,0 @@
|
||||
:PROPERTIES:
|
||||
:ID: 53fadc75-f48e-461e-be06-44a1e88b2abe
|
||||
:ROAM_EXCLUDE: t
|
||||
:END:
|
||||
#+TITLE: Excluded by Org-roam
|
||||
|
||||
This node is excluded by declaring ~ROAM_EXCLUDE: t~.
|
||||
@@ -24,43 +24,20 @@
|
||||
(require 'buttercup)
|
||||
(require 'org-roam)
|
||||
|
||||
(describe "org-roam-list-files"
|
||||
(before-each
|
||||
(setq org-roam-directory (expand-file-name "tests/roam-files")
|
||||
org-roam-db-location (expand-file-name "org-roam.db" temporary-file-directory)
|
||||
org-roam-file-extensions '("org")
|
||||
org-roam-file-exclude-regexp nil))
|
||||
|
||||
(it "gets files correctly"
|
||||
(expect (length (org-roam-list-files))
|
||||
:to-equal 3))
|
||||
|
||||
(it "respects org-roam-file-extensions"
|
||||
(setq org-roam-file-extensions '("md"))
|
||||
(expect (length (org-roam-list-files)) :to-equal 1)
|
||||
(setq org-roam-file-extensions '("org" "md"))
|
||||
(expect (length (org-roam-list-files)) :to-equal 4))
|
||||
|
||||
(it "respects org-roam-file-exclude-regexp"
|
||||
(setq org-roam-file-exclude-regexp (regexp-quote "foo.org"))
|
||||
(expect (length (org-roam-list-files)) :to-equal 2)))
|
||||
|
||||
(describe "org-roam-db-sync"
|
||||
(before-all
|
||||
(setq org-roam-directory (expand-file-name "tests/roam-files")
|
||||
org-roam-db-location (expand-file-name "org-roam.db" temporary-file-directory)
|
||||
org-roam-file-extensions '("org")
|
||||
org-roam-file-exclude-regexp nil)
|
||||
(org-roam-db-sync))
|
||||
org-roam-db-location (expand-file-name "org-roam.db" temporary-file-directory))
|
||||
(org-roam-setup))
|
||||
|
||||
(after-all
|
||||
(org-roam-db--close)
|
||||
(org-roam-teardown)
|
||||
(delete-file org-roam-db-location))
|
||||
|
||||
(it "has the correct number of files"
|
||||
(expect (caar (org-roam-db-query [:select (funcall count) :from files]))
|
||||
:to-equal
|
||||
3))
|
||||
2))
|
||||
|
||||
(it "has the correct number of nodes"
|
||||
(expect (caar (org-roam-db-query [:select (funcall count) :from nodes]))
|
||||
@@ -70,13 +47,7 @@
|
||||
(it "has the correct number of links"
|
||||
(expect (caar (org-roam-db-query [:select (funcall count) :from links]))
|
||||
:to-equal
|
||||
1))
|
||||
|
||||
(it "respects ROAM_EXCLUDE"
|
||||
;; The excluded node has ID "53fadc75-f48e-461e-be06-44a1e88b2abe"
|
||||
(expect (mapcar #'car (org-roam-db-query [:select id :from nodes]))
|
||||
:to-have-same-items-as
|
||||
'("884b2341-b7fe-434d-848c-5282c0727861" "440795d0-70c1-4165-993d-aebd5eef7a24"))))
|
||||
1)))
|
||||
|
||||
(provide 'test-org-roam)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user