awesome-emacs/org-roam
1
0
Fork 0
mirror of https://github.com/org-roam/org-roam synced 2025-08-01 12:17:21 -05:00
Code Issues Packages Projects Releases Wiki Activity

Org-roam V2 (#1401)

Browse Source
This commit is contained in:
Jethro Kuan
2021-07-17 19:29:30 +08:00
committed by GitHub
parent 756f6215b6
commit aee3467b3e
49 changed files with 4597 additions and 7186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
.dir-locals.el
View File

@ -1,6 +1,13 @@
;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")
((emacs-lisp-mode
(eval . (require 'org-roam-dev))
(eval . (org-roam-dev-mode))))
(fill-column . 110)
(indent-tabs-mode . nil)
(elisp-lint-ignored-validators . ("byte-compile" "package-lint"))
(elisp-lint-indent-specs . ((describe . 1)
(it . 1)
(org-element-map . defun)
(org-roam-with-temp-buffer . 1)
(org-with-point-at . 1)
(magit-insert-section . defun)
(magit-section-case . 0)
(->> . 1)
(org-roam-with-file . 2)))))

37
.github/workflows/test.yml vendored
View File

@ -34,39 +34,28 @@ jobs:
build:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
emacs_version:
- 27.1
- snapshot
steps:
- uses: purcell/setup-emacs@master
with:
version: ${{ matrix.emacs_version }}
- uses: purcell/setup-emacs@master
with:
version: ${{ matrix.emacs_version }}
- uses: actions/checkout@v2
- uses: actions/checkout@v2
- name: Create Sandbox Directory
run: |
SANDBOX_DIR=$(mktemp -d) || exit 1
echo "SANDBOX_DIR=$SANDBOX_DIR" >> $GITHUB_ENV
- name: Install Eldev
run: curl -fsSL https://raw.github.com/doublep/eldev/master/webinstall/github-eldev | sh
- name: Initialize Sandbox
run: |
./makem.sh -vv --sandbox $SANDBOX_DIR --install-deps --install-linters
- name: Install dependencies
run: make prepare
# The "all" rule is not used, because it treats compilation warnings
# as failures, so linting and testing are run as separate steps.
# org-roam-compat is excluded from linting because it contains
# symbols/aliases from other packages
- name: Lint
continue-on-error: false
run: ./makem.sh -vv --sandbox $SANDBOX_DIR --exclude org-roam-compat.el lint
- name: Test
if: always() # Run test even if linting fails.
run: ./makem.sh -vv --sandbox $SANDBOX_DIR test
- name: Lint
run: make lint
- name: Test
run: make test
# Local Variables:
# eval: (outline-minor-mode)
# End:

1
.gitignore vendored
View File

@ -13,3 +13,4 @@
/doc/stats/
/config.mk
/doc/manual.html
/.eldev/

9
CHANGELOG.md
View File

@ -1,17 +1,21 @@
# Changelog
## 1.2.4 (TBD)
### 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
### Changed
- [#1352](https://github.com/org-roam/org-roam/pull/1352) prefer lower-case for roam_tag and roam_alias in interactive commands
- [#1513](https://github.com/org-roam/org-roam/pull/1513) replaced hardcoded "svg" with defcustom org-roam-graph-filetype
- [#1540](https://github.com/org-roam/org-roam/pull/1540) allow `roam_tag` and `roam_alias` to be specified on multiple lines
### Fixed
- [#1281](https://github.com/org-roam/org-roam/pull/1281) fixed idle-timer not instantiated on `org-roam-mode`
- [#1308](https://github.com/org-roam/org-roam/pull/1308) fixed file renames corrupting database
- [#1325](https://github.com/org-roam/org-roam/pull/1325) make titles and tags extracted unique per note
@ -20,7 +24,7 @@
- [#1347](https://github.com/org-roam/org-roam/pull/1347) allow use of `%a` element in regular Org-roam captures
- [#1352](https://github.com/org-roam/org-roam/pull/1352) fixed org-roam-{tag/alias}-{add/delete} altering the original case of the Org property
- [#1374](https://github.com/org-roam/org-roam/pull/1374) fix headline completions erroring out
- [#1375](https://github.com/org-roam/org-roam/pull/1375) fix org-roam-protocol to use existing ref file
- [#1375](https://github.com/org-roam/org-roam/pull/1375) fix org-roam-protocol to use existing ref file
- [#1403](https://github.com/org-roam/org-roam/issues/1403) fixed inconsistency between how we write and read props like alias and tags
- [#1409](https://github.com/org-roam/org-roam/issues/1398) prevent inclusion of non-org-roam files in `org-roam-dailies--list-files`
- [#1542](https://github.com/org-roam/org-roam/issues/1542) fix files not excluded when `org-roam-list-files-commands` is nil
@ -32,6 +36,7 @@ Primarily a stabilization and bug-fix release.
Org-roam-dailies has also been revamped to include new features, see [this video](https://www.youtube.com/watch?v=1q9x2aZCJJ4) for a quick overview.
### Added
- [#978](https://github.com/org-roam/org-roam/pull/978) Revamp org-roam-dailies
- [#1183](https://github.com/org-roam/org-roam/pull/1183) Interactive functions for managing aliases and tags in Org-roam file, namely `org-roam-alias-add`, `org-roam-alias-delete`, `org-roam-tag-add`, and `org-roam-tag-delete`.
- [#1215](https://github.com/org-roam/org-roam/pull/1215) Multiple `ROAM_KEY` keywords can now be specified in one file. This allows bibliographical entries to share the same note file.
@ -40,9 +45,11 @@ Org-roam-dailies has also been revamped to include new features, see [this video
- [#1264](https://github.com/org-roam/org-roam/pull/1264) add `org-roam-db-update-method` to control when the cache is rebuilt.
### Changed
- [#1264](https://github.com/org-roam/org-roam/pull/1264) renamed `org-roam-update-db-idle-seconds` to `org-roam-db-idle-idle-seconds`
### Fixed
- [#1074](https://github.com/org-roam/org-roam/issues/1074) fix `org-roam--extract-links` to handle content boundaries.
- [#1193](https://github.com/org-roam/org-roam/issues/1193) fix `org-roam-db-build-cache` by not killing temporary buffer in `org-roam--extract-links`.
- [#1195](https://github.com/org-roam/org-roam/issues/1195) fix ID face showing as invalid if within Org ID files, but not Org-roam's.

29
Eldev Normal file
View File

@ -0,0 +1,29 @@
; -*- mode: emacs-lisp; lexical-binding: t; no-byte-compile: t -*-
;; explicitly set main file
(setf eldev-project-main-file "org-roam.el")
(eldev-use-package-archive 'gnu)
(eldev-use-package-archive 'melpa-unstable)
;; allow to load test helpers
(eldev-add-loading-roots 'test "test/utils")
;; Tell checkdoc not to demand two spaces after a period.
(setq sentence-end-double-space nil)
(setf eldev-lint-default '(elisp))
(setf eldev-standard-excludes `(:or ,eldev-standard-excludes "org-roam-macs.el"))
(with-eval-after-load 'elisp-lint
;; We will byte-compile with Eldev.
(setf elisp-lint-ignored-validators '("package-lint" "fill-column")
enable-local-variables :all))
;; Teach linter how to properly indent emacsql vectors
(eldev-add-extra-dependencies 'lint 'emacsql)
(add-hook 'eldev-lint-hook
(lambda ()
(eldev-load-project-dependencies 'lint nil t)
(require 'emacsql)
(call-interactively #'emacsql-fix-vector-indentation)))

73
Makefile
View File

@ -1,70 +1,29 @@
# * makem.sh/Makefile --- Script to aid building and testing Emacs Lisp packages
.PHONY: clean
clean:
eldev clean all
# This Makefile is from the makem.sh repo: <https://github.com/alphapapa/makem.sh>.
.PHONY: prepare
prepare:
eldev -C --unstable -p -dtT prepare
# * Arguments
.PHONY: lint
lint:
eldev -C --unstable -T lint
# For consistency, we use only var=val options, not hyphen-prefixed options.
# NOTE: I don't like duplicating the arguments here and in makem.sh,
# but I haven't been able to find a way to pass arguments which
# conflict with Make's own arguments through Make to the script.
# Using -- doesn't seem to do it.
ifdef install-deps
INSTALL_DEPS = "--install-deps"
endif
ifdef install-linters
INSTALL_LINTERS = "--install-linters"
endif
ifdef sandbox
ifeq ($(sandbox), t)
SANDBOX = --sandbox
else
SANDBOX = --sandbox $(sandbox)
endif
endif
ifdef debug
DEBUG = "--debug"
endif
# ** Verbosity
# Since the "-v" in "make -v" gets intercepted by Make itself, we have
# to use a variable.
verbose = $(v)
ifneq (,$(findstring vv,$(verbose)))
VERBOSE = "-vv"
else ifneq (,$(findstring v,$(verbose)))
VERBOSE = "-v"
endif
# * Rules
# TODO: Handle cases in which "test" or "tests" are called and a
# directory by that name exists, which can confuse Make.
%:
@./makem.sh $(DEBUG) $(VERBOSE) $(SANDBOX) $(INSTALL_DEPS) $(INSTALL_LINTERS) $(@)
.DEFAULT: init
init:
@./makem.sh $(DEBUG) $(VERBOSE) $(SANDBOX) $(INSTALL_DEPS) $(INSTALL_LINTERS)
.PHONY: test
test:
eldev -C --unstable -T test
docs:
@$(MAKE) -C doc all
make -C doc all
html:
@$(MAKE) -C doc html-dir
make -C doc html-dir
install: install-docs
install-docs: docs
@$(MAKE) -C doc install-docs
make -C doc install-docs
install-info: info
@$(MAKE) -C doc install-info
make -C doc install-info

22
README.md
View File

@ -1,5 +1,5 @@
# Org-roam [![GitHub Release][release-badge]][release] [![MELPA][melpa-badge]][melpa] [![License GPL 3][gpl3-badge]][gpl3]
<img src="https://www.orgroam.com/img/logo.svg" align="right" alt="Org-roam Logo" width="240">
Org-roam is a plain-text knowledge management system. It brings some of
@ -44,17 +44,19 @@ Here's a sample configuration with `use-package`:
```emacs-lisp
(use-package org-roam
:ensure t
:hook
(after-init . org-roam-mode)
:custom
(org-roam-directory (file-truename "/path/to/org-files/"))
:bind (:map org-roam-mode-map
(("C-c n l" . org-roam)
("C-c n f" . org-roam-find-file)
("C-c n g" . org-roam-graph))
:map org-mode-map
(("C-c n i" . org-roam-insert))
(("C-c n I" . org-roam-insert-immediate))))
: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))
```
The `file-truename` function is only necessary when you use symbolic links

1790
doc/org-roam.org
View File

File diff suppressed because it is too large Load Diff

702
doc/org-roam.texi
View File

@ -25,13 +25,13 @@ General Public License for more details.
@dircategory Emacs
@direntry
* Org-roam: (org-roam). Rudimentary Roam Replica for Emacs.
* Org-roam: (org-roam). Roam Research for Emacs.
@end direntry
@finalout
@titlepage
@title Org-roam User Manual
@subtitle for version 1.2.3
@subtitle for version 2.0.0
@author Jethro Kuan
@page
@vskip 0pt plus 1filll
@ -44,10 +44,10 @@ General Public License for more details.
@noindent
This manual is for Org-roam version 1.2.3.
This manual is for Org-roam version 2.0.0.
@quotation
Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@@gmail.com>
Copyright (C) 2020-2021 Jethro Kuan <jethrokuan95@@gmail.com>
You can redistribute this document and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation, either
@ -67,13 +67,24 @@ General Public License for more details.
* A Brief Introduction to the Zettelkasten Method::
* Installation::
* Getting Started::
* Files::
* Viewing the links::
* Node Properties::
* The Org-roam Buffer::
* Styling Org-roam::
* Completion::
* Encryption::
* Org-roam protocol::
* Diagnosing and Repair::
* Building Extensions::
* The Org-mode Ecosystem::
* Frequently Asked Questions::
* Developer's Guide to Org-roam::
* The Templating System::
* Concepts and Configuration::
* Inserting Links::
* Completions::
* Navigating Around::
* Encryption::
* Encryption: Encryption (1).
* Graphing::
* Minibuffer Completion::
* Roam Protocol::
@ -91,31 +102,33 @@ General Public License for more details.
@detailmenu
--- The Detailed Node Listing ---
A Brief Introduction to the Zettelkasten Method
* Fleeting notes::
* Permanent notes::
Installation
* Installing from MELPA::
* Installing from Apt::
* Installing from the Git Repository::
* Installing from Source::
* Post-Installation Tasks::
Files
Getting Started
* File Titles::
* File Tags::
* File Refs::
* The Org-roam Node::
* Links between Nodes::
* Setting up Org-roam::
* Creating and Linking Nodes::
File Titles
Node Properties
* Customizing Title Extraction::
* Standard Org properties::
* Aliases::
* Refs::
File Tags
Building Extensions
* Customizing Tag Extraction::
* Public Interface::
Developer's Guide to Org-roam
* Org-roam's Design Principles::
The Templating System
@ -125,10 +138,9 @@ The Templating System
Concepts and Configuration
* Directories and Files::
* The Org-roam Buffer::
* The Org-roam Buffer: The Org-roam Buffer (1).
* Org-roam Files::
* Org-roam Faces::
* The Database::
Completions
@ -198,28 +210,24 @@ FAQ
@node Introduction
@chapter Introduction
Org-roam is a tool for network thought. It reproduces some of @uref{https://roamresearch.com/, Roam
Research's} @footnote{To understand more about Roam, a collection of links are available in @ref{Note-taking Workflows}.} features within the all-powerful @uref{https://orgmode.org/, Org-mode}.
Org-roam is a tool for networked thought. It reproduces some of @uref{https://roamresearch.com/, Roam
Research's} @footnote{To understand more about Roam, a collection of links are available in @ref{Note-taking Workflows}.} key features within @uref{https://orgmode.org/, Org-mode}.
Org-roam is a solution for effortless non-hierarchical note-taking with
Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy.
Org-roam keeps closely to Org syntax, and will work for anyone already using
Org-mode for their personal wiki.
Org-roam allows for effortless non-hierarchical note-taking: with Org-roam,
notes flow naturally, making note-taking fun and easy. Org-roam augments the
Org-mode syntax, and will work for anyone already using Org-mode for their
personal wiki.
Org-roam gains its superpowers by leveraging the mature ecosystem around
Org-mode. For example, it has first-class support for @uref{https://github.com/jkitchin/org-ref, org-ref} for citation
management.
Org-roam leverages the mature ecosystem around Org-mode. For example, it has
first-class support for @uref{https://github.com/jkitchin/org-ref, org-ref} for citation management, and is able to
piggyback off Org's excellent @LaTeX{} and source-block evaluation capabilities.
Org-roam aims to implement the core features of Roam, leveraging the
mature ecosystem around Org-mode where possible. Eventually, we hope
to further introduce features enabled by the Emacs ecosystem.
Org-roam provides several benefits over other tooling:
Org-roam provides these benefits over other tooling:
@itemize
@item
@strong{Privacy and Security:} Keep your personal wiki entirely offline and in your
control. Encrypt your notes with GPG@.
@strong{Privacy and Security:} Your personal wiki belongs only to you, entirely
offline and in your control. Encrypt your notes with GPG@.
@item
@strong{Longevity of Plain Text:} Unlike web solutions like Roam Research, the notes
@ -235,13 +243,13 @@ you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
or open a pull request.
@item
@strong{Leverage the Org-mode ecosystem:} Over the years, Emacs and Org-mode has
@strong{Leverage the Org-mode ecosystem:} Over the decades, Emacs and Org-mode has
developed into a mature system for plain-text organization. Building upon
Org-mode already puts Org-roam light-years ahead of many other solutions.
@item
@strong{Built on Emacs:} Emacs is also a fantastic interface for editing text, and we
can inherit many of the powerful text-navigation and editing packages
@strong{Built on Emacs:} Emacs is also a fantastic interface for editing text, and
Org-roam inherits many of the powerful text-navigation and editing packages
available to Emacs.
@end itemize
@ -249,18 +257,18 @@ available to Emacs.
@chapter Target Audience
Org-roam is a tool that will appear unfriendly to anyone unfamiliar with Emacs
and Org-mode, but is also extremely powerful to those willing to put effort in
mastering the intricacies of the tools. Org-roam stands on the shoulders on
giants. Emacs was first created in 1976, and remains a top tier tool for editing
and Org-mode, but it is also extremely powerful to those willing to put effort
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
lists, planning projects, and authoring documents. Both of these tools are
incredibly vast and require significant time investment to master.
Org-roam assumes basic familiarity with these tools. It is not difficult to get
up and running with basic text-editing functionality, but one will only fully
appreciate the power of building Roam functionality into Emacs and Org-mode when
the usage of these tools become more advanced.
Org-roam assumes only basic familiarity with these tools. It is not difficult to
get up and running with basic text-editing functionality, but one will only
fully appreciate the power of building Roam functionality into Emacs and
Org-mode when the usage of these tools become more advanced.
One key advantage to Org-roam is that building on top of Emacs gives it
malleability. This is especially important for note-taking workflows. It is our
@ -313,13 +321,7 @@ plain-text, Org-mode file. In the same way one would maintain a paper slip-box,
Org-roam makes it easy to create new zettels, pre-filling boilerplate content
using a powerful templating system.
@menu
* Fleeting notes::
* Permanent notes::
@end menu
@node Fleeting notes
@section Fleeting notes
@strong{Fleeting notes}
A slip-box requires a method for quickly capturing ideas. These are called
@strong{fleeting notes}: they are simple reminders of information or ideas that will
@ -328,8 +330,7 @@ need to be processed later on, or trashed. This is typically accomplished using
functionality (see @ref{Daily-notes}). This provides a central inbox for collecting
thoughts, to be processed later into permanent notes.
@node Permanent notes
@section Permanent notes
@strong{Permanent notes}
Permanent notes are further split into two categories: @strong{literature notes} and
@strong{concept notes}. Literature notes can be brief annotations on a particular
@ -338,6 +339,9 @@ Concept notes require much more care in authoring: they need to be
self-explanatory and detailed. Org-roam's templating system supports the
addition of different templates to facilitate the creation of these notes.
For further reading on the Zettelkasten method, ``How to Take Smart Notes'' by
Sonke Ahrens is a decent guide.
@node Installation
@chapter Installation
@ -347,7 +351,7 @@ development repository.
@menu
* Installing from MELPA::
* Installing from Apt::
* Installing from the Git Repository::
* Installing from Source::
* Post-Installation Tasks::
@end menu
@ -416,8 +420,8 @@ apt-get install elpa-org-roam
Org-roam will then be autoloaded into Emacs.
@node Installing from the Git Repository
@section Installing from the Git Repository
@node Installing from Source
@section Installing from Source
You may install Org-roam directly from the repository on @uref{https://github.com/org-roam/org-roam, GitHub} if you like.
This will give you access to the latest version hours or days before it appears
@ -520,18 +524,19 @@ install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
@node Post-Installation Tasks
@section Post-Installation Tasks
Org-roam uses @code{emacsql-sqlite3}, which requires @code{sqlite3} to be located on
@code{exec-path}. Please ensure that @code{sqlite3} is installed appropriately on your
operating system. You can verify that this is the case by executing:
Org-roam requires @code{sqlite3} to be locatable by Emacs (i.e. on @code{exec-path}).
Please ensure that @code{sqlite3} is installed appropriately on your operating
system. You can verify that this is the case by executing @footnote{Two easy ways to evaluate elisp: 1) Place the cursor after the closing
paren and run @samp{M-x eval-last-sexp RET} or 2) Press @samp{C-c C-c} with your cursor in
an Org file code block (like @samp{#+BEGIN_SRC emacs-lisp}).}:
@lisp
(executable-find "sqlite3")
@end lisp
If you have @code{sqlite3} installed, and @code{executable-find} still reports @code{nil}, then
it is likely that the path to the executable is not a member of the Emacs
variable @code{exec-path}. You may rectify this by manually adding the path within
your Emacs configuration:
the path to the executable is not a member of the Emacs variable @code{exec-path}.
Rectify this by manually adding the path within your Emacs configuration:
@lisp
(add-to-list 'exec-path "path/to/sqlite3")
@ -540,283 +545,145 @@ your Emacs configuration:
@node Getting Started
@chapter Getting Started
This short tutorial describes the essential commands used in Org-roam, to help
you get started.
@menu
* The Org-roam Node::
* Links between Nodes::
* Setting up Org-roam::
* Creating and Linking Nodes::
@end menu
First, it is important to understand how Org-roam was designed. Org-roam was
built to support a workflow that was not possible with vanilla Org-mode. This
flow is modelled after the @uref{https://zettelkasten.de/, Zettelkasten Method}, and many of @uref{https://roamresearch.com, Roam Research's}
workflows. Org-roam does not magically make note-taking better -- this often
requires a radical change in your current note-taking workflow. To understand
more about the methods and madness, see @ref{Note-taking Workflows}.
@node The Org-roam Node
@section The Org-roam Node
We first begin with some terminology we'll use throughout the manual. We term
the basic denomination in Org-roam a node. We define a node as follows:
@quotation
A node is any headline or top level file with an ID@.
@end quotation
For example, with this example file content:
@example
:PROPERTIES:
:ID: foo
:END:
#+title: Foo
* Bar
:PROPERTIES:
:ID: bar
:END:
@end example
We create two nodes:
@itemize
@item
A file node ``Foo'' with id @code{foo}.
@item
A headline node ``Bar'' with id @code{bar}.
@end itemize
Headlines without IDs will not be considered Org-roam nodes. Org IDs can be
added to files or headlines via the interactive command @code{M-x org-id-get-create}.
@node Links between Nodes
@section Links between Nodes
We link between nodes using Org's standard ID link (e.g. @code{id:foo}). While only
ID links will be considered during the computation of links between nodes,
Org-roam caches all other links in the documents for external use.
@node Setting up Org-roam
@section Setting up Org-roam
Org-roam's capabilities stem from its aggressive caching: it crawls all files
within @code{org-roam-directory}, keeping a cache of all its links and nodes, while
making sure that the cache is consistent.
To first start using Org-roam, one needs to pick a location to store the
Org-roam files. The directory that will contain your notes is specified by the
variable @code{org-roam-directory}. This variable needs to be set before any calls to
Org-roam functions, including enabling @code{org-roam-mode}. For this tutorial,
create an empty directory, and set @code{org-roam-directory}:
variable @code{org-roam-directory}. Org-roam searches recursively within
@code{org-roam-directory} for notes. This variable needs to be set before any calls
to Org-roam functions. For this tutorial, create an empty directory, and set
@code{org-roam-directory}:
@lisp
(make-directory "~/org-roam")
(setq org-roam-directory "~/org-roam")
@end lisp
We encourage using a flat hierarchy for storing notes, but some prefer using
folders for storing specific kinds of notes (e.g. websites, papers). This is
fine; Org-roam searches recursively within @code{org-roam-directory} for notes.
Instead of relying on the file hierarchy for any form of categorization, one
should use links between files to establish connections between notes.
Next, we need to enable the global minor mode @code{org-roam-mode}. This sets up
Emacs with several hooks, building a cache that is kept consistent as your
slip-box grows. We recommend starting @code{org-roam-mode} on startup:
Next, we need to setup Org-roam to maintain cache consistency. This is achieved
by running @code{M-x org-roam-setup}. To ensure that Org-roam is available on
startup, one can place this in their Emacs configuration:
@lisp
(add-hook 'after-init-hook 'org-roam-mode)
(require 'org-roam)
(org-roam-setup)
@end lisp
To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. Cache
builds may take a while the first time, but is often instantaneous in subsequent
runs because it only reprocesses modified files.
Let us now create our first note. Call @code{M-x org-roam-find-file}. This shows a
list of titles for notes that reside in @code{org-roam-directory}. It should show
nothing right now, since there are no notes in the directory. Entering the title
of the note you wish to create, and pressing @code{RET} should begin the note
@node 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:
@itemize
@item
@code{org-roam-node-insert}: creates a node if it does not exist, and inserts a
link to the node at point.
@item
@code{org-roam-node-find}: creates a node if it does not exist, and visits the
node.
@end itemize
Let's first try @code{org-roam-node-find}. Calling @code{M-x org-roam-node-find} will
show a list of titles for nodes that reside in @code{org-roam-directory}. It should
show nothing right now, since there are no notes in the directory. Enter the
title of the note you wish to create, and press @code{RET}. This begins the note
creation process. This process uses @code{org-capture}'s templating system, and can
be customized (see @ref{The Templating System}). Using the default template, pressing
@code{C-c C-c} finishes the note capture.
By default, Org-roam updates the cache asynchronously in the background to
avoid getting in the way of writing. Org-roam queues updates to the files,
waits for you to be idle for 2 seconds, and then automatically triggers
updating the cache. After the cache has been updated, running @code{M-x
org-roam-find-file} again should show the note you have created, and selecting
that entry will bring you to that note @footnote{Depending on your completion framework, you may need to press TAB to
see the list.}. One can customize the waiting
time by setting @code{org-roam-db-update-idle-seconds}; or change the cache update
to be triggered immediately after buffer save by setting
@code{org-roam-db-update-method} to @code{'immediate}.
Now that we have a node, we can try inserting a link to the node using @code{M-x
org-roam-node-insert}. This brings up the list of nodes, which should contain
the node you just created. Selecting the node will insert an @code{id:} link to the
node. If you instead entered a title that does not exist, you will once again be
brought through the node creation process. To enable link auto-completion,
see @ref{Completion}.
For experienced @code{org-capture} users, the behavior of @code{M-x org-roam-find-file}
may seem unfamiliar: after finishing a capture with @code{C-c C-c}, you are returned
not to the original buffer from which you called @code{M-x org-roam-find-file}, but
to a buffer pointing to the note you just created. For the usual @code{org-capture}
behavior you can call @code{M-x org-roam-capture} instead of @code{M-x org-roam-find-file}.
@node Viewing the links
@chapter @strong{TODO} Viewing the links
Org-roam makes it easy to create notes, and link them together. To link notes
together, we call @code{M-x org-roam-insert}. This brings up a prompt with a list of
title for existing notes. Selecting an existing entry will create and insert a
link to the current file. Entering a non-existent title will create a new note
with that title. Good usage of Org-roam requires liberally linking files: this
facilitates building up a dense graph of inter-connected notes.
Org-roam provides an interface to view relationships with other notes
(backlinks, reference links, unlinked references etc.). To pop up this info
buffer, call @code{M-x org-roam-buffer}.
Org-roam provides an interface to view backlinks. It shows backlinks for the
currently active Org-roam note, along with some surrounding context. To toggle
the visibility of this buffer, call @code{M-x org-roam}.
For a visual representation of the notes and their connections, Org-roam also
provides graphing capabilities, using Graphviz. It generates graphs with notes
as nodes, and links between them as edges. The generated graph can be used to
navigate to the files, but this requires some additional setup (see @ref{Roam Protocol}).
@node Files
@chapter Files
In Org-roam, notes typically consist of multiple files, where each file is a
zettel.
While the bulk of Org-roam's functionality is built on top of vanilla Org-mode,
Org-roam adds several Org-roam-specific keywords to support additional
functionality.
This section explains the important components of a file, and the extensions to
Org-mode.
@node Node Properties
@chapter @strong{TODO} Node Properties
@menu
* File Titles::
* File Tags::
* File Refs::
* Standard Org properties::
* Aliases::
* Refs::
@end menu
@node File Titles
@section File Titles
@node Standard Org properties
@section @strong{TODO} Standard Org properties
To easily find a note, a title needs to be prescribed to a note.
@node Aliases
@section @strong{TODO} Aliases
A note can have many titles: this allows a note to be referred to by different
names, which is especially useful for topics or concepts with acronyms. For
example, for a note like ``World War 2'', it may be desirable to also refer to it
using the acronym ``WWII''.
Org-roam calls @code{org-roam--extract-titles} to extract titles. It uses the
variable @code{org-roam-title-sources}, to control how the titles are extracted. The
title extraction methods supported are:
@itemize
@item
@code{'title}: This extracts the title using the file @code{#+title} property
@item
@code{'headline}: This extracts the title from the first headline in the Org file
@item
@code{'alias}: This extracts a list of titles using the @code{#+roam_alias} property.
The aliases are space-delimited, and can be multi-worded using quotes.
@end itemize
Take for example the following org file:
@example
#+title: World War 2
#+roam_alias: "WWII" "World War II"
* Headline
@end example
@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Method
@tab Titles
@item @code{'title}
@tab '(``World War 2'')
@item @code{'headline}
@tab '(``Headline'')
@item @code{'alias}
@tab '(``WWII'' ``World War II'')
@end multitable
If no title is provided, Org-roam defaults to using the file-path.
@menu
* Customizing Title Extraction::
@end menu
@node Customizing Title Extraction
@subsection Customizing Title Extraction
To control how Org-roam extracts titles, customize @code{org-roam-title-sources}. If
all methods of title extraction return no results, the file-name is used as the
note's title.
@defopt org-roam-title-sources
The list of sources from which to retrieve a note title.
Each element in the list is either:
@end defopt
@itemize
@item
a symbol -- this symbol corresponds to a title retrieval function, which
returns the list of titles for the current buffer
@itemize
@item
a list of symbols -- symbols in the list are treated as with (1). The
return value of this list is the first symbol in the list returning a
non-nil value.
@end itemize
The return results of the root list are concatenated.
For example the setting: '((title headline) alias) means the following:
@itemize
@item
Return the 'title + 'alias, if the title of current buffer is non-empty;
@item
Or return 'headline + 'alias otherwise.
@end itemize
The currently supported symbols are:
@code{'title}
The @code{#+title} property of org file.
@code{'alias}
The @code{#+roam_alias} property of the org file, using
space-delimited strings.
@code{'headline}
The first headline in the org file.
@end itemize
Adding your own title extraction method requires two steps. First, define a
method @code{(defun org-roam--extract-titles-foo () ...)}, where @code{foo} a
self-prescribed name for the title extraction method. This method takes no
arguments, and returns a list of strings (titles). Finally, push the symbol
@code{foo} into @code{org-roam-title-sources}. You may need to rebuild the cache from
scratch to re-process all files to pick up the new titles.
@node File Tags
@section File Tags
Tags are used as meta-data for files: they facilitate interactions with notes
where titles are insufficient. For example, tags allow for categorization of
notes: differentiating between bibliographical and structure notes during
interactive commands.
By default, tags are extracted from the @code{#+roam_tags} property. To add
additional extraction methods, see @ref{Customizing Tag Extraction}.
@menu
* Customizing Tag Extraction::
@end menu
@node Customizing Tag Extraction
@subsection Customizing Tag Extraction
Org-roam calls @code{org-roam--extract-tags} to extract tags from files. The variable
@code{org-roam-tag-sources}, to control how tags are extracted.
@defopt org-roam-tag-sources
@end defopt
Sources to obtain tags from.
It should be a list of symbols representing any of the following extraction
methods:
@code{'prop}
Extract tags from the @code{#+roam_tags} property.
Tags are space delimited.
Tags may contain spaces if they are double-quoted.
e.g. @code{#+roam_tags: TAG "tag with spaces"}
@code{'vanilla}
Extract vanilla org-mode tags, including @code{#+FILETAGS} and
inherited tags.
@code{'all-directories}
Extract sub-directories relative to @code{org-roam-directory}.
That is, if a file is located at relative path foo/bar/file.org,
the file will have tags ``foo'' and ``bar''.
@code{'last-directory}
Extract the last directory relative to `org-roam-directory'.
That is, if a file is located at relative path foo/bar/file.org,
the file will have tag \``bar\''.
@code{'first-directory}
Extract the first directory relative to @code{org-roam-directory}.
That is, if a file is located at relative path foo/bar/file.org,
the file will have tag ``foo''
By default, only the @code{'prop} extraction method is enabled. To enable the other
extraction methods, you may modify @code{org-roam-tag-sources}, for example:
@lisp
(setq org-roam-tag-sources '(prop last-directory))
@end lisp
Adding your own tag extraction method requires two steps. First, define a method
@code{(defun org-roam--extract-tags-foo (file) ...)}, where @code{foo} a self-prescribed
name for the tag extraction method. This method takes the file path as an
argument, and returns a list of strings (titles). Finally, push the symbol @code{foo}
into @code{org-roam-tag-sources}. You may need to rebuild the cache from scratch to
re-process all files to pick up the new tags.
@node File Refs
@section File Refs
@node Refs
@section @strong{TODO} Refs
Refs are unique identifiers for files. For example, a note for a website may
contain a ref:
@ -849,6 +716,159 @@ You may assign multiple refs to a single file, for example when you want
multiple papers in a series to share the same note, or an article has a citation
key and a URL at the same time.
@node The Org-roam Buffer
@chapter @strong{TODO} The Org-roam Buffer
@node Styling Org-roam
@chapter @strong{TODO} Styling Org-roam
@node Completion
@chapter @strong{TODO} Completion
@node Encryption
@chapter @strong{TODO} Encryption
@node Org-roam protocol
@chapter @strong{TODO} Org-roam protocol
@node Diagnosing and Repair
@chapter @strong{TODO} Diagnosing and Repair
@node Building Extensions
@chapter @strong{TODO} Building Extensions
@menu
* Public Interface::
@end menu
@node Public Interface
@section @strong{TODO} Public Interface
Database (for developers)
@itemize
@item
querying: (org-roam-db-query)
@item
updating full database: (org-roam-db-sync)
@item
update current file: (org-roam-db-update-file)
@item
remove file from database: (org-roam-db-clear-file)
@end itemize
Nodes:
@itemize
@item
List all nodes
@item
Read a node in from completion
@item
Get node at point
@end itemize
Links:
@itemize
@item
Get backlinks for node
@end itemize
Tags:
@itemize
@item
Add tag to node
@item
delete tag for node
@item
Get tags for node
@end itemize
Aliases:
@itemize
@item
Add alias to node
@item
Delete alias for node
@item
Get aliases for node
@end itemize
Ref:
@itemize
@item
Add ref to node
@end itemize
Capture:
Navigation:
@itemize
@item
Find or create a node
@end itemize
@node The Org-mode Ecosystem
@chapter @strong{TODO} The Org-mode Ecosystem
@node Frequently Asked Questions
@chapter @strong{TODO} Frequently Asked Questions
@node Developer's Guide to Org-roam
@chapter @strong{TODO} Developer's Guide to Org-roam
@menu
* Org-roam's Design Principles::
@end menu
@node Org-roam's Design Principles
@section Org-roam's Design Principles
Org-roam is primarily motivated by the need for a dual representation. We
(humans) love operating in a plain-text environment. The syntax rules of
Org-mode are simple and fit snugly within our brain. This also allows us to use
the tools and packages we love to explore and edit our notes. Org-mode is simply
the most powerful plain-text format available, with support for images, @LaTeX{},
TODO planning and much more.
But this plain-text format is simply ill-suited for exploration of these notes:
plain-text is simply not amenable for answering large-scale, complex queries
(e.g. how many tasks do I have that are due by next week?). Interfaces such as
Org-agenda slow to a crawl when the number of files becomes unwieldy, which
can quickly become the case.
At its core, Org-roam provides a database abstraction layer, providing a dual
representation of what's already available in plain-text. This allows us
(humans) to continue working with plain-text, while programs can utilize the
database layer to perform complex queries. These capabilities include, but are
not limited to:
@itemize
@item
link graph traversal and visualization
@item
Instantaneous SQL-like queries on headlines
@itemize
@item
What are my TODOs, scheduled for X, or due by Y@?
@end itemize
@end itemize
All of these functionality is powered by this database abstraction layer. Hence,
at its core Org-roam's primary goal is to provide a resilient dual
representation that is cheap to maintain, easy to understand, and is as
up-to-date as it possibly can. Org-roam also then exposes an API to this
database abstraction layer for users who would like to perform programmatic
queries on their Org files.
@node The Templating System
@chapter The Templating System
@ -918,7 +938,7 @@ The template is given a description of @code{"default"}.
@code{(function org-roam--capture-get-point)} should not be changed.
@item
@code{"%?"} is the template inserted on each call to @code{org-roam-capture--capture}.
@code{"%?"} is the template inserted on each call to @code{org-roam-capture-}.
This template means don't insert any content, but place the cursor here.
@item
@ -990,10 +1010,9 @@ org-roam}.
@menu
* Directories and Files::
* The Org-roam Buffer::
* The Org-roam Buffer: The Org-roam Buffer (1).
* Org-roam Files::
* Org-roam Faces::
* The Database::
@end menu
@node Directories and Files
@ -1021,7 +1040,7 @@ with multiple Org-roam instances.
Files matching this regular expression are excluded from the Org-roam.
@end defvar
@node The Org-roam Buffer
@node The Org-roam Buffer (1)
@section The Org-roam Buffer
The Org-roam buffer displays backlinks for the currently active Org-roam note.
@ -1086,27 +1105,6 @@ The @code{org-roam-link-current} face corresponds to links to the same file it i
The @code{org-roam-link-invalid} face is applied to links that are broken. These are
links to files or IDs that cannot be found.
@node The Database
@section @strong{TODO} The Database
Org-roam is backed by a Sqlite database.
@defopt org-roam-db-update-method
Method to update the Org-roam database.
@code{'immediate}: Update the database immediately upon file changes.
@code{'idle-timer}: Updates the database if dirty, if Emacs idles for
@code{org-roam-db-update-idle-seconds}.
@end defopt
@defopt org-roam-db-update-idle-seconds
Number of idle seconds before triggering an Org-roam database update. This is
only valid if @code{org-roam-db-update-method} is @code{'idle-timer}.
@end defopt
@node Inserting Links
@chapter Inserting Links
@ -1194,7 +1192,7 @@ represents the cursor:
@code{[[|]]}: completes for a file title
@item
@code{[[roam:]]}: completes for a file title
@code{[[roam:|]]}: completes for a file title
@item
@code{[[*|]]}: completes for a headline within this file
@ -1206,6 +1204,9 @@ represents the cursor:
@code{[[roam:foo*|]]} completes a headline within the file with title ``foo''
@end itemize
If you don't see the literal display of your links like the above examples,
call @code{M-x org-toggle-link-display}
Completions account for the current input. For example, for @code{[[f|]]}, the
completions (by default) only show for files with titles that start with ``f''.
@ -1279,7 +1280,7 @@ title is @code{"Index"}.
Opens the Index file in the current @code{org-roam-directory}.
@end defun
@node Encryption
@node Encryption (1)
@chapter Encryption
One may wish to keep private, encrypted files. Org-roam supports encryption (via
@ -1617,7 +1618,7 @@ in the generated graph.
@node The roam-ref protocol
@section The roam-ref protocol
This protocol finds or creates a new note with a given @code{roam_key} (see @ref{Files}):
This protocol finds or creates a new note with a given @code{roam_key}:
@image{images/roam-ref,,,,gif}
@ -1720,7 +1721,7 @@ template @code{j} will put its notes under the heading ‘Journal’.
Create an entry in the daily note for today.
When @code{goto} is non-nil, go the note without creating an entry.
When @code{goto} is non-nil, go to the note without creating an entry.
@end defun
@defun @code{org-roam-dailies-find-today}
@ -1986,22 +1987,6 @@ using @uref{https://github.com/raxod502/el-patch, el-patch}:
(eval-when-compile
(require 'el-patch))
(use-package deft
;; same as above...
:config/el-patch
(defun deft-parse-title (file contents)
"Parse the given FILE and CONTENTS and determine the title.
If `deft-use-filename-as-title' is nil, the title is taken to
be the first non-empty line of the FILE. Else the base name of the FILE is
used as title."
(el-patch-swap (if deft-use-filename-as-title
(deft-base-filename file)
(let ((begin (string-match "^.+$" contents)))
(if begin
(funcall deft-parse-title-function
(substring contents begin (match-end 0))))))
(org-roam-db--get-title file))))
@end lisp
The Deft interface can slow down quickly when the number of files get huge.
@ -2105,6 +2090,9 @@ file with the right @samp{#+roam_key}.
@uref{https://www.leonrische.me/fc/index.html, Org-fc} is a spaced repetition system that scales well with a large number of
files. Other alternatives include @uref{https://orgmode.org/worg/org-contrib/org-drill.html, org-drill}, and @uref{https://github.com/abo-abo/pamparam, pamparam}.
To use Anki for spaced repetition, @uref{https://github.com/louietan/anki-editor, anki-editor} allows you to write your cards in
Org-mode, and sync your cards to Anki via @uref{https://github.com/FooSoft/anki-connect#installation, anki-connect}.
@node FAQ
@chapter FAQ

1087
makem.sh
View File

File diff suppressed because it is too large Load Diff

357
org-roam-buffer.el
View File

@ -1,357 +0,0 @@
;;; org-roam-buffer.el --- Metadata buffer -*- 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: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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 the org-roam-buffer functionality for org-roam
;;; Code:
;;;; Library Requires
(eval-when-compile (require 'subr-x))
(require 'cl-lib)
(require 'dash)
(require 's)
(require 'f)
(require 'ol)
(require 'org-element)
(require 'org-roam-macs)
(defvar org-roam-directory)
(defvar org-link-frame-setup)
(defvar org-return-follows-link)
(defvar org-roam-backlinks-mode)
(defvar org-roam-last-window)
(defvar org-ref-cite-types) ;; in org-ref-core.el
(defvar org-roam-mode)
(defvar org-roam--org-link-bracket-typed-re)
(declare-function org-roam-db--ensure-built "org-roam-db")
(declare-function org-roam-db--get-title "org-roam-db")
(declare-function org-roam-db-has-file-p "org-roam-db")
(declare-function org-roam--extract-refs "org-roam")
(declare-function org-roam--extract-titles "org-roam")
(declare-function org-roam--get-backlinks "org-roam")
(declare-function org-roam-backlinks-mode "org-roam")
(declare-function org-roam-mode "org-roam")
(declare-function org-roam--find-file "org-roam")
(declare-function org-roam-format-link "org-roam")
(declare-function org-roam-link-get-path "org-roam-link")
(defcustom org-roam-buffer-position 'right
"Position of `org-roam' buffer.
Valid values are
* left,
* right,
* top,
* bottom,
* a function returning one of the above."
:type '(choice (const left)
(const right)
(const top)
(const bottom)
function)
:group 'org-roam)
(defcustom org-roam-buffer-width 0.33
"Width of `org-roam' buffer.
Has an effect if and only if `org-roam-buffer-position' is `left' or `right'."
:type 'number
:group 'org-roam)
(defcustom org-roam-buffer-height 0.27
"Height of `org-roam' buffer.
Has an effect if and only if `org-roam-buffer-position' is `top' or `bottom'."
:type 'number
:group 'org-roam)
(defcustom org-roam-buffer "*org-roam*"
"Org-roam buffer name."
:type 'string
:group 'org-roam)
(defcustom org-roam-buffer-prepare-hook '(org-roam-buffer--insert-title
org-roam-buffer--insert-backlinks
org-roam-buffer--insert-ref-links)
"Hook run in the `org-roam-buffer' before it is displayed."
:type 'hook
:group 'org-roam)
(defcustom org-roam-buffer-preview-function #'org-roam-buffer--preview
"Function to obtain preview contents for a given link.
The function takes in two arguments, the FILE containing the
link, and the POINT of the link."
:type 'function
:group 'org-roam)
(defcustom org-roam-buffer-window-parameters nil
"Additional window parameters for the `org-roam-buffer' side window.
For example: (setq org-roam-buffer-window-parameters '((no-other-window . t)))"
:type '(alist)
:group 'org-roam)
(defvar org-roam-buffer--current nil
"Currently displayed file in `org-roam' buffer.")
(defun org-roam-buffer--find-file (file)
"Open FILE in the window `org-roam' was called from."
(setq file (expand-file-name file))
(let ((last-window org-roam-last-window))
(if (window-valid-p last-window)
(progn (with-selected-window last-window
(org-roam--find-file file))
(select-window last-window))
(org-roam--find-file file))))
(defun org-roam-buffer--insert-title ()
"Insert the org-roam-buffer title."
(insert (propertize (org-roam-db--get-title
(buffer-file-name org-roam-buffer--current))
'font-lock-face
'org-document-title)))
(defun org-roam-buffer--preview (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)))
(or (org-element-property :raw-value elem)
(when-let ((begin (org-element-property :begin elem))
(end (org-element-property :end elem)))
(string-trim (buffer-substring-no-properties begin end))))))))
(defun org-roam-buffer--pluralize (string number)
"Conditionally pluralize STRING if NUMBER is above 1."
(let ((l (pcase number
((pred (listp)) (length number))
((pred (integerp)) number)
(wrong-type (signal 'wrong-type-argument
`((listp integerp)
,wrong-type))))))
(concat string (when (> l 1) "s"))))
(defun org-roam-buffer-expand-links (content orig-path)
"Crawl CONTENT for relative links and corrects them to be correctly displayed.
ORIG-PATH is the path where the CONTENT originated."
(with-temp-buffer
(insert content)
(goto-char (point-min))
(let (link link-type)
(while (re-search-forward org-roam--org-link-bracket-typed-re (point-max) t)
(setq link-type (match-string 1)
link (match-string 2))
(when (and (string-equal link-type "file")
(f-relative-p link))
(replace-match (org-roam-link-get-path (expand-file-name link (file-name-directory orig-path)))
nil t nil 2))))
(buffer-string)))
(defun org-roam-buffer--insert-ref-links ()
"Insert ref backlinks for the current buffer."
(when-let* ((refs (with-temp-buffer
(insert-buffer-substring org-roam-buffer--current)
(org-roam--extract-refs)))
(paths (mapcar #'cdr refs)))
(if-let* ((key-backlinks (mapcan #'org-roam--get-backlinks paths))
(grouped-backlinks (--group-by (nth 0 it) key-backlinks)))
(progn
(insert (let ((l (length key-backlinks)))
(format "\n\n* %d %s\n"
l (org-roam-buffer--pluralize "Ref Backlink" l))))
(dolist (group grouped-backlinks)
(let ((file-from (car group))
(bls (cdr group)))
(insert (format "** %s\n"
(org-roam-format-link file-from
(org-roam-db--get-title file-from)
"file")))
(dolist (backlink bls)
(pcase-let ((`(,file-from _ ,props) backlink))
(insert (if-let ((content (funcall org-roam-buffer-preview-function file-from (plist-get props :point))))
(propertize (org-roam-buffer-expand-links content file-from)
'help-echo "mouse-1: visit backlinked note"
'file-from file-from
'file-from-point (plist-get props :point))
"")
"\n\n"))))))
(insert "\n\n* No ref backlinks!"))))
(defun org-roam-buffer--insert-backlinks ()
"Insert the org-roam-buffer backlinks string for the current buffer."
(let (props file-from)
(if-let* ((file-path (buffer-file-name org-roam-buffer--current))
(titles (with-current-buffer org-roam-buffer--current
(org-roam--extract-titles)))
(backlinks (org-roam--get-backlinks (push file-path titles)))
(grouped-backlinks (--group-by (nth 0 it) backlinks)))
(progn
(insert (let ((l (length backlinks)))
(format "\n\n* %d %s\n"
l (org-roam-buffer--pluralize "Backlink" l))))
(dolist (group grouped-backlinks)
(setq file-from (car group))
(setq props (mapcar (lambda (row) (nth 2 row)) (cdr group)))
(setq props (seq-sort-by (lambda (p) (plist-get p :point)) #'< props))
(insert (format "** %s\n"
(org-roam-format-link file-from
(org-roam-db--get-title file-from)
"file")))
(dolist (prop props)
(insert "*** "
(if-let ((outline (plist-get prop :outline)))
(-> outline
(string-join " > ")
(org-roam-buffer-expand-links file-from))
"Top")
"\n"
(if-let ((content (funcall org-roam-buffer-preview-function file-from (plist-get prop :point))))
(propertize
(s-trim (s-replace "\n" " " (org-roam-buffer-expand-links content file-from)))
'help-echo "mouse-1: visit backlinked note"
'file-from file-from
'file-from-point (plist-get prop :point))
"")
"\n\n"))))
(insert "\n\n* No backlinks!"))))
(defun org-roam-buffer-update ()
"Update the `org-roam-buffer'."
(interactive)
(org-roam-db--ensure-built)
(let* ((source-org-roam-directory org-roam-directory))
(with-current-buffer org-roam-buffer
;; When dir-locals.el is used to override org-roam-directory,
;; org-roam-buffer should have a different local org-roam-directory and
;; default-directory, as relative links are relative from the overridden
;; org-roam-directory.
(setq-local org-roam-directory source-org-roam-directory)
(setq-local default-directory source-org-roam-directory)
;; Locally overwrite the file opening function to re-use the
;; last window org-roam was called from
(setq-local org-link-frame-setup
(cons '(file . org-roam--find-file) org-link-frame-setup))
(let ((inhibit-read-only t))
(erase-buffer)
(unless (eq major-mode 'org-mode)
(org-mode))
(unless org-roam-backlinks-mode
(org-roam-backlinks-mode))
(make-local-variable 'org-return-follows-link)
(setq org-return-follows-link t)
(run-hooks 'org-roam-buffer-prepare-hook)
(read-only-mode 1)))))
(cl-defun org-roam-buffer--update-maybe (&key redisplay)
"Reconstructs `org-roam-buffer'.
This needs to be quick or infrequent, because this is run at
`post-command-hook'. If REDISPLAY, force an update of
`org-roam-buffer'."
(let ((buffer (window-buffer)))
(when (and (or redisplay
(not (eq org-roam-buffer--current buffer)))
(eq 'visible (org-roam-buffer--visibility))
(buffer-file-name buffer)
(org-roam-db-has-file-p (buffer-file-name buffer)))
(setq org-roam-buffer--current buffer)
(org-roam-buffer-update))))
;;;; Toggling the org-roam buffer
(define-inline org-roam-buffer--visibility ()
"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
(cond
((get-buffer-window org-roam-buffer) 'visible)
((get-buffer org-roam-buffer) 'exists)
(t 'none))))
(defun org-roam-buffer--set-width (width)
"Set the width of `org-roam-buffer' to `WIDTH'."
(unless (one-window-p)
(let ((window-size-fixed)
(w (max width window-min-width)))
(cond
((> (window-width) w)
(shrink-window-horizontally (- (window-width) w)))
((< (window-width) w)
(enlarge-window-horizontally (- w (window-width))))))))
(defun org-roam-buffer--set-height (height)
"Set the height of `org-roam-buffer' to `HEIGHT'."
(unless (one-window-p)
(let ((window-size-fixed)
(h (max height window-min-height)))
(cond
((> (window-height) h)
(shrink-window (- (window-height) h)))
((< (window-height) h)
(enlarge-window (- h (window-height))))))))
(defun org-roam-buffer--get-create ()
"Set up the `org-roam' buffer at `org-roam-buffer-position'."
(let ((position (if (functionp org-roam-buffer-position)
(funcall org-roam-buffer-position)
org-roam-buffer-position)))
(save-selected-window
(-> (get-buffer-create org-roam-buffer)
(display-buffer-in-side-window
`((side . ,position)
(window-parameters . ,org-roam-buffer-window-parameters)))
(select-window))
(pcase position
((or 'right 'left)
(org-roam-buffer--set-width
(round (* (frame-width) org-roam-buffer-width))))
((or 'top 'bottom)
(org-roam-buffer--set-height
(round (* (frame-height) org-roam-buffer-height))))))))
(defun org-roam-buffer-activate ()
"Activate display of the `org-roam-buffer'."
(interactive)
(unless org-roam-mode (org-roam-mode))
(setq org-roam-last-window (get-buffer-window))
(org-roam-buffer--get-create))
(defun org-roam-buffer-deactivate ()
"Deactivate display of the `org-roam-buffer'."
(interactive)
(setq org-roam-last-window (get-buffer-window))
(delete-window (get-buffer-window org-roam-buffer)))
(defun org-roam-buffer-toggle-display ()
"Toggle display of the `org-roam-buffer'."
(interactive)
(pcase (org-roam-buffer--visibility)
('visible (org-roam-buffer-deactivate))
((or 'exists 'none) (org-roam-buffer-activate))))
(provide 'org-roam-buffer)
;;; org-roam-buffer.el ends here

1101
org-roam-capture.el
View File

File diff suppressed because it is too large Load Diff

77
org-roam-compat.el
View File

@ -5,8 +5,8 @@
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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.
@ -34,78 +34,7 @@
;;;; Library Requires
;;; Obsolete aliases (remove after next major release)
;;;; Functions
(define-obsolete-function-alias 'org-roam--capture-get-point 'org-roam-capture--get-point
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-build-cache 'org-roam-db-build-cache
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-sql 'org-roam-db-query
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam--db-clear 'org-roam-db--clear
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-show-graph 'org-roam-graph-show
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam--maybe-update-buffer
'org-roam-buffer--update-maybe "org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam--current-visibility
'org-roam-buffer--visibility "org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-update 'org-roam-buffer-update
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam--set-width 'org-roam-buffer--set-width
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam--set-height 'org-roam-buffer--set-height
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam--set-up-buffer 'org-roam-buffer--get-create
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-today 'org-roam-dailies-today
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-tomorrow 'org-roam-dailies-tomorrow
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-yesterday 'org-roam-dailies-yesterday
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-date 'org-roam-dailies-date
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-graph-show 'org-roam-graph
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-graph-build 'org-roam-graph
"org-roam 1.0.0")
(define-obsolete-function-alias 'org-roam-find-index 'org-roam-jump-to-index
"org-roam 1.1.0")
(define-obsolete-function-alias 'org-roam--pluralize 'org-roam-buffer--pluralize
"org-roam 1.1.0")
(define-obsolete-function-alias 'org-roam--capture 'org-roam-capture--capture
"org-roam 1.1.0")
(define-obsolete-function-alias 'org-roam-db--clear 'org-roam-db-clear
"org-roam 1.2.0")
(define-obsolete-function-alias 'org-roam-dailies-today 'org-roam-dailies-find-today
"org-roam 1.2.2")
(define-obsolete-function-alias 'org-roam-dailies-yesterday 'org-roam-dailies-find-yesterday
"org-roam 1.2.2")
(define-obsolete-function-alias 'org-roam-dailies-tomorrow 'org-roam-dailies-find-tomorrow
"org-roam 1.2.2")
(define-obsolete-function-alias 'org-roam-dailies-date 'org-roam-dailies-find-date
"org-roam 1.2.2")
;;;; Variables
(define-obsolete-variable-alias 'org-roam-graphviz-extra-options
'org-roam-graph-extra-config "org-roam 1.0.0")
(define-obsolete-variable-alias 'org-roam-grapher-extra-options
'org-roam-graph-extra-config "org-roam 1.0.0")
(define-obsolete-variable-alias 'org-roam-graph-node-shape
'org-roam-graph-node-extra-config "org-roam 1.0.0")
(define-obsolete-variable-alias 'org-roam--db-connection
'org-roam-db--connection "org-roam 1.0.0")
(define-obsolete-variable-alias 'org-roam--current-buffer
'org-roam-buffer--current "org-roam 1.0.0")
(define-obsolete-variable-alias 'org-roam-date-title-format
'org-roam-dailies-capture-templates "org-roam 1.0.0")
(define-obsolete-variable-alias 'org-roam-date-filename-format
'org-roam-dailies-capture-templates "org-roam 1.0.0")
(define-obsolete-variable-alias 'org-roam-update-db-idle-seconds
'org-roam-db-update-idle-seconds "org-roam 1.2.2")
(make-obsolete-variable 'org-roam-buffer-no-delete-other-windows
'org-roam-buffer-window-parameters "org-roam 1.1.1")
;;; Obsolete functions
(provide 'org-roam-compat)

148
org-roam-completion.el
View File

@ -5,9 +5,8 @@
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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
@ -27,90 +26,81 @@
;;; Commentary:
;;
;; This library provides completion for org-roam.
;; 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:
;;;; Library Requires
(require 'cl-lib)
(require 's)
(require 'org-element)
(defvar helm-pattern)
(declare-function helm "ext:helm")
(declare-function helm-make-source "ext:helm-source" (name class &rest args) t)
(declare-function org-roam--get-titles "org-roam")
(defcustom org-roam-completion-system 'default
"The completion system to be used by `org-roam'."
:type '(radio
(const :tag "Default" default)
(const :tag "Ido" ido)
(const :tag "Ivy" ivy)
(const :tag "Helm" helm)
(function :tag "Custom function"))
:group 'org-roam)
(defcustom org-roam-completion-ignore-case t
"Whether to ignore case in Org-roam `completion-at-point' completions."
(defcustom org-roam-completion-everywhere nil
"When non-nil, provide link completion matching outside of Org links."
:group 'org-roam
:type 'boolean)
(defun org-roam-completion--helm-candidate-transformer (candidates _source)
"Transforms CANDIDATES for Helm-based completing read.
SOURCE is not used."
(let ((prefix (propertize "[?] "
'face 'helm-ff-prefix)))
(cons (propertize helm-pattern
'display (concat prefix helm-pattern))
candidates)))
(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.")
(cl-defun org-roam-completion--completing-read (prompt choices &key
require-match initial-input
action)
"Present a PROMPT with CHOICES and optional INITIAL-INPUT.
If REQUIRE-MATCH is t, the user must select one of the CHOICES.
Return user choice."
(let (res)
(setq res
(cond
((eq org-roam-completion-system 'ido)
(let ((candidates (mapcar #'car choices)))
(ido-completing-read prompt candidates nil require-match initial-input)))
((eq org-roam-completion-system 'default)
(completing-read prompt choices nil require-match initial-input))
((eq org-roam-completion-system 'ivy)
(if (fboundp 'ivy-read)
(ivy-read prompt choices
:initial-input initial-input
:preselect initial-input
:require-match require-match
:action (prog1 action
(setq action nil))
:caller 'org-roam--completing-read)
(user-error "Please install ivy from \
https://github.com/abo-abo/swiper")))
((eq org-roam-completion-system 'helm)
(unless (and (fboundp 'helm)
(fboundp 'helm-make-source))
(user-error "Please install helm from \
https://github.com/emacs-helm/helm"))
(let ((source (helm-make-source prompt 'helm-source-sync
:candidates (mapcar #'car choices)
:filtered-candidate-transformer
(and (not require-match)
#'org-roam-completion--helm-candidate-transformer)))
(buf (concat "*org-roam "
(s-downcase (s-chop-suffix ":" (s-trim prompt)))
"*")))
(or (helm :sources source
:action (if action
(prog1 action
(setq action nil))
#'identity)
:prompt prompt
:input initial-input
:buffer buf)
(keyboard-quit))))))
(if action
(funcall action res)
res)))
(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)

309
org-roam-dailies.el
View File

@ -4,11 +4,11 @@
;; Copyright © 2020 Leo Vivier <leo.vivier+dev@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; Leo Vivier <leo.vivier+dev@gmail.com>
;; Leo Vivier <leo.vivier+dev@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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.
@ -36,20 +36,23 @@
;;; Library Requires
(require 'org-capture)
(require 'org-roam-capture)
(require 'org-roam-macs)
(require 'f)
;;;; Declarations
(defvar org-roam-mode)
(defvar org-roam-directory)
(defvar org-roam-file-extensions)
(declare-function org-roam--org-file-p "org-roam")
(declare-function org-roam--find-file "org-roam")
(declare-function org-roam-mode "org-roam")
(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)
;;;; Customizable variables
(defcustom org-roam-dailies-directory "daily/"
"Path to daily-notes."
"Path to daily-notes.
This path is relative to `org-roam-directory'."
:group 'org-roam
:type 'string)
@ -59,120 +62,117 @@
:type 'hook)
(defcustom org-roam-dailies-capture-templates
`(("d" "default" entry (function org-roam-capture--get-point)
`(("d" "default" entry
"* %?"
:file-name ,(concat org-roam-dailies-directory "%<%Y-%m-%d>")
:head "#+title: %<%Y-%m-%d>\n"))
"Capture templates for daily-notes in Org-roam."
:if-new (file+head "%<%Y-%m-%d>.org"
"#+title: %<%Y-%m-%d>\n")))
"Capture templates for daily-notes in Org-roam.
See `org-roam-capture-templates' for the template documentation."
:group 'org-roam
;; Adapted from `org-capture-templates'
:type
`(repeat
(choice :value ("d" "default" plain (function org-roam-capture--get-point)
"%?"
:file-name ,(concat org-roam-dailies-directory
"%<%Y-%m-%d>")
:head "#+title: %<%Y-%m-%d>\n"
:unnarrowed t)
(list :tag "Multikey description"
(string :tag "Keys ")
(string :tag "Description"))
(list :tag "Template entry"
(string :tag "Keys ")
(string :tag "Description ")
(choice :tag "Type "
(const :tag "Plain" plain)
(const :tag "Entry (for creating headlines)" entry))
(const :format "" #'org-roam-capture--get-point)
(choice :tag "Template "
(string :tag "String"
:format "String:\n \
Template string :\n%v")
(list :tag "File"
(const :format "" file)
(file :tag "Template file "))
(list :tag "Function"
(const :format "" function)
(function :tag "Template function ")))
(const :format "File name format :" :file-name)
(string :format " %v" :value ,(concat org-roam-dailies-directory
"%<%Y-%m-%d>"))
(const :format "Header format :" :head)
(string :format " %v" :value "#+title: ${title}\n")
(plist :inline t
:tag "Options"
;; Give the most common options as checkboxes
:options
(((const :tag "Outline path" :olp)
(repeat :tag "Headings"
(string :tag "Heading")))
((const :format "%v " :unnarrowed) (const t))
((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 " :table-line-pos) (string))
((const :format "%v " :kill-buffer) (const t))))))))
;;;; Utilities
(defun org-roam-dailies-directory--get-absolute-path ()
"Get absolute path to `org-roam-dailies-directory'."
(expand-file-name org-roam-dailies-directory org-roam-directory))
: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))))))))
;;;###autoload
(defun org-roam-dailies-find-directory ()
"Find and open `org-roam-dailies-directory'."
(interactive)
(org-roam--find-file (org-roam-dailies-directory--get-absolute-path)))
(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 (or file
(-> (buffer-base-buffer)
(buffer-file-name))))
(directory (org-roam-dailies-directory--get-absolute-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--org-file-p path)
(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."
(unless org-roam-mode (org-roam-mode))
(let ((org-roam-capture-templates (--> org-roam-dailies-capture-templates
(if goto (list (car it)) it)))
(org-roam-capture--info (list (cons 'time time)))
(org-roam-capture--context 'dailies))
(org-roam-capture--capture (when goto '(4)))))
(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.
When GOTO is non-nil, go the note without creating an entry."
(interactive "P")
(org-roam-dailies--capture (current-time) goto)
(when goto
(run-hooks 'org-roam-dailies-find-file-hook)))
(org-roam-dailies--capture (current-time) goto))
(defun org-roam-dailies-find-today ()
;;;###autoload
(defun org-roam-dailies-goto-today ()
"Find the daily-note for today, creating it if necessary."
(interactive)
(org-roam-dailies-capture-today t))
;;; Tomorrow
;;;###autoload
(defun org-roam-dailies-capture-tomorrow (n &optional goto)
"Create an entry in the daily-note for tomorrow.
@ -183,7 +183,8 @@ creating an entry."
(interactive "p")
(org-roam-dailies--capture (time-add (* n 86400) (current-time)) goto))
(defun org-roam-dailies-find-tomorrow (n)
;;;###autoload
(defun org-roam-dailies-goto-tomorrow (n)
"Find the daily-note for tomorrow, creating it if necessary.
With numeric argument N, use the daily-note N days in the
@ -192,6 +193,7 @@ future."
(org-roam-dailies-capture-tomorrow n t))
;;; Yesterday
;;;###autoload
(defun org-roam-dailies-capture-yesterday (n &optional goto)
"Create an entry in the daily-note for yesteday.
@ -201,7 +203,8 @@ When GOTO is non-nil, go the note without creating an entry."
(interactive "p")
(org-roam-dailies-capture-tomorrow (- n) goto))
(defun org-roam-dailies-find-yesterday (n)
;;;###autoload
(defun org-roam-dailies-goto-yesterday (n)
"Find the daily-note for yesterday, creating it if necessary.
With numeric argument N, use the daily-note N days in the
@ -210,68 +213,46 @@ future."
(org-roam-dailies-capture-tomorrow (- n) t))
;;; Calendar
(defvar org-roam-dailies-calendar-hook (list 'org-roam-dailies-calendar-mark-entries)
"Hooks to run when showing the `org-roam-dailies-calendar'.")
(defun org-roam-dailies-calendar--install-hook ()
"Install Org-roam-dailies hooks to calendar."
(add-hook 'calendar-today-visible-hook #'org-roam-dailies-calendar--run-hook)
(add-hook 'calendar-today-invisible-hook #'org-roam-dailies-calendar--run-hook))
(defun org-roam-dailies-calendar--run-hook ()
"Run Org-roam-dailies hooks to calendar."
(run-hooks 'org-roam-dailies-calendar-hook)
(remove-hook 'calendar-today-visible-hook #'org-roam-dailies-calendar--run-hook)
(remove-hook 'calendar-today-invisible-hook #'org-roam-dailies-calendar--run-hook))
(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)))))
(buffer-base-buffer (buffer-file-name)))))
(cl-destructuring-bind (_ _ _ d m y _ _ _)
(-> file
(file-name-nondirectory)
(file-name-sans-extension)
(org-parse-time-string))
(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 the calendar (MONTH DAY YEAR) to a time."
"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 (org-roam-dailies-directory--get-absolute-path))
(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.
Prefer past dates, unless PREFER-FUTURE is non-nil.
With a `C-u' prefix or when GOTO is non-nil, go the note without
creating an entry."
(interactive "P")
(org-roam-dailies-calendar--install-hook)
(let* ((time-str (let ((org-read-date-prefer-future prefer-future))
(org-read-date nil nil nil (if goto
"Find daily-note: "
"Capture to daily-note: "))))
(time (org-read-date nil t time-str)))
(org-roam-dailies--capture time goto)
(when goto
(run-hooks 'org-roam-dailies-find-file-hook))))
(let ((time (let ((org-read-date-prefer-future prefer-future))
(org-read-date t t nil (if goto
"Find daily-note: "
"Capture to daily-note: ")))))
(org-roam-dailies--capture time goto)))
(defun org-roam-dailies-find-date (&optional prefer-future)
;;;###autoload
(defun org-roam-dailies-goto-date (&optional prefer-future)
"Find the daily-note for a date using the calendar, creating it if necessary.
Prefer past dates, unless PREFER-FUTURE is non-nil."
(interactive)
(org-roam-dailies-capture-date t prefer-future))
@ -280,8 +261,8 @@ Prefer past dates, unless PREFER-FUTURE is non-nil."
(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 (org-roam-dailies-directory--get-absolute-path))
(regexp (rx-to-string `(and "." (or ,@org-roam-file-extensions)))))
(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)
@ -290,7 +271,7 @@ EXTRA-FILES can be used to append extra files to the list."
(directory-files-recursively dir regexp))
extra-files)))
(defun org-roam-dailies-find-next-note (&optional n)
(defun org-roam-dailies-goto-next-note (&optional n)
"Find next daily-note.
With numeric argument N, find note N days in the future. If N is
@ -305,27 +286,30 @@ negative, find note N days in the past."
(string= (buffer-file-name (buffer-base-buffer)) candidate))
dailies))
note)
(unless position
(user-error "Can't find current note file - have you saved it yet?"))
(pcase n
((pred (natnump))
(when (eq position (- (length dailies) 1))
(user-error "Already at newest note")))
((pred (integerp))
(when (eq position 0)
(user-error "Already at oldest note"))))
(setq note (nth (+ position n) dailies))
(find-file note)
(run-hooks 'org-roam-dailies-find-file-hook)))
(unless position
(user-error "Can't find current note file - have you saved it yet?"))
(pcase n
((pred (natnump))
(when (eq position (- (length dailies) 1))
(user-error "Already at newest note")))
((pred (integerp))
(when (eq position 0)
(user-error "Already at oldest note"))))
(setq note (nth (+ position n) dailies))
(find-file note)
(run-hooks 'org-roam-dailies-find-file-hook)))
(defun org-roam-dailies-find-previous-note (&optional n)
(defun org-roam-dailies-goto-previous-note (&optional n)
"Find previous daily-note.
With numeric argument N, find note N days in the past. If N is
negative, find note N days in the future."
(interactive "p")
(let ((n (if n (- n) -1)))
(org-roam-dailies-find-next-note n)))
(org-roam-dailies-goto-next-note n)))
(add-hook 'calendar-today-visible-hook #'org-roam-dailies-calendar-mark-entries)
(add-hook 'calendar-today-invisible-hook #'org-roam-dailies-calendar-mark-entries)
;;;; Bindings
(defvar org-roam-dailies-map (make-sparse-keymap)
@ -333,16 +317,35 @@ negative, find note N days in the future."
(define-prefix-command 'org-roam-dailies-map)
(define-key org-roam-dailies-map (kbd "d") #'org-roam-dailies-find-today)
(define-key org-roam-dailies-map (kbd "y") #'org-roam-dailies-find-yesterday)
(define-key org-roam-dailies-map (kbd "t") #'org-roam-dailies-find-tomorrow)
(define-key org-roam-dailies-map (kbd "d") #'org-roam-dailies-goto-today)
(define-key org-roam-dailies-map (kbd "y") #'org-roam-dailies-goto-yesterday)
(define-key org-roam-dailies-map (kbd "t") #'org-roam-dailies-goto-tomorrow)
(define-key org-roam-dailies-map (kbd "n") #'org-roam-dailies-capture-today)
(define-key org-roam-dailies-map (kbd "f") #'org-roam-dailies-find-next-note)
(define-key org-roam-dailies-map (kbd "b") #'org-roam-dailies-find-previous-note)
(define-key org-roam-dailies-map (kbd "c") #'org-roam-dailies-find-date)
(define-key org-roam-dailies-map (kbd "f") #'org-roam-dailies-goto-next-note)
(define-key org-roam-dailies-map (kbd "b") #'org-roam-dailies-goto-previous-note)
(define-key org-roam-dailies-map (kbd "c") #'org-roam-dailies-goto-date)
(define-key org-roam-dailies-map (kbd "v") #'org-roam-dailies-capture-date)
(define-key org-roam-dailies-map (kbd ".") #'org-roam-dailies-find-directory)
(define-obsolete-function-alias
'org-roam-dailies-find-today
'org-roam-dailies-goto-today "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-yesterday
'org-roam-dailies-goto-yesterday "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-tomorrow
'org-roam-dailies-goto-tomorrow "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-next-note
'org-roam-dailies-goto-next-note "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-previous-note
'org-roam-dailies-goto-previous-note "org-roam 2.0")
(define-obsolete-function-alias
'org-roam-dailies-find-date
'org-roam-dailies-goto-date "org-roam 2.0")
(provide 'org-roam-dailies)
;;; org-roam-dailies.el ends here

722
org-roam-db.el
View File

@ -5,8 +5,8 @@
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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,37 +27,31 @@
;;; Commentary:
;;
;; This library is provides the underlying database api to org-roam
;; This library provides the underlying database api to org-roam.
;;
;;; Code:
;;;; Library Requires
(eval-when-compile (require 'subr-x))
(require 'emacsql)
(require 'emacsql-sqlite3)
(require 'emacsql-sqlite)
(require 'seq)
(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-enable-headline-linking)
(defvar org-roam-verbose)
(defvar org-roam-file-name)
(defvar org-agenda-files)
(declare-function org-roam--org-roam-file-p "org-roam")
(declare-function org-roam--extract-titles "org-roam")
(declare-function org-roam--extract-refs "org-roam")
(declare-function org-roam--extract-tags "org-roam")
(declare-function org-roam--extract-ids "org-roam")
(declare-function org-roam--extract-links "org-roam")
(declare-function org-roam--list-all-files "org-roam")
(declare-function org-roam--path-to-slug "org-roam")
(declare-function org-roam--file-name-extension "org-roam")
(declare-function org-roam-buffer--update-maybe "org-roam-buffer")
(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)
@ -71,7 +65,7 @@ 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 large, heavy operations like `org-roam-db-build-cache',
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
@ -84,34 +78,20 @@ value like `most-positive-fixnum'."
:type 'int
:group 'org-roam)
(defconst org-roam-db--version 10)
(defcustom org-roam-db-node-include-function (lambda () t)
"A custom function to check if the headline at point is a node."
:type 'function
:group 'org-roam)
(defconst org-roam-db-version 16)
(defconst org-roam--sqlite-available-p
(with-demoted-errors "Org-roam initialization: %S"
(emacsql-sqlite-ensure-binary)
t))
(defvar org-roam-db--connection (make-hash-table :test #'equal)
"Database connection to Org-roam database.")
(defvar org-roam-db-dirty nil
"Whether the org-roam database is dirty and requires an update.
Contains pairs of `org-roam-directory' and `org-roam-db-location'
so that multi-directories are updated.")
(defcustom org-roam-db-update-method 'idle-timer
"Method to update the Org-roam database.
`immediate'
Update the database immediately upon file changes.
`idle-timer'
Updates the database if dirty, if Emacs idles for
`org-roam-db-update-idle-seconds'."
:type '(choice (const :tag "idle-timer" idle-timer)
(const :tag "immediate" immediate))
:group 'org-roam)
(defcustom org-roam-db-update-idle-seconds 2
"Number of idle seconds before triggering an Org-roam database update."
:type 'integer
:group 'org-roam)
;;;; Core Functions
(defun org-roam-db--get-connection ()
@ -127,7 +107,7 @@ Performs a database upgrade when required."
(emacsql-live-p (org-roam-db--get-connection)))
(let ((init-db (not (file-exists-p org-roam-db-location))))
(make-directory (file-name-directory org-roam-db-location) t)
(let ((conn (emacsql-sqlite3 org-roam-db-location)))
(let ((conn (emacsql-sqlite org-roam-db-location)))
(set-process-query-on-exit-flag (emacsql-process conn) nil)
(puthash (expand-file-name org-roam-directory)
conn
@ -137,72 +117,103 @@ Performs a database upgrade when required."
(let* ((version (caar (emacsql conn "PRAGMA user_version")))
(version (org-roam-db--upgrade-maybe conn version)))
(cond
((> version org-roam-db--version)
((> version org-roam-db-version)
(emacsql-close conn)
(user-error
"The Org-roam database was created with a newer Org-roam version. "
"You need to update the Org-roam package"))
((< version org-roam-db--version)
((< version org-roam-db-version)
(emacsql-close conn)
(error "BUG: The Org-roam database scheme changed %s"
"and there is no upgrade path")))))))
(org-roam-db--get-connection))
;;;; 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.
SQL can be either the emacsql vector representation, or a string."
(if (stringp sql)
(emacsql (org-roam-db) (apply #'format sql args))
(apply #'emacsql (org-roam-db) sql args)))
(apply #'emacsql (org-roam-db) sql args))
(defun org-roam-db-query! (handler sql &rest args)
"Run SQL query on Org-roam database with ARGS.
SQL can be either the emacsql vector representation, or a string.
The query is expected to be able to fail, in this situation, run HANDLER."
(condition-case err
(org-roam-db-query sql args)
(emacsql-constraint
(funcall handler err))))
;;;; Schemata
(defconst org-roam-db--table-schemata
'((files
[(file :unique :primary-key)
(hash :not-null)
(meta :not-null)])
(atime :not-null)
(mtime :not-null)])
(ids
[(id :unique :primary-key)
(file :not-null)
(level :not-null)])
(nodes
([(id :not-null :primary-key)
(file :not-null)
(level :not-null)
(pos :not-null)
todo
priority
(scheduled text)
(deadline text)
title
properties
olp]
(:foreign-key [file] :references files [file] :on-delete :cascade)))
(links
[(source :not-null)
(dest :not-null)
(type :not-null)
(properties :not-null)])
(tags
[(file :unique :primary-key)
(tags)])
(titles
[(file :not-null)
title])
(aliases
([(node-id :not-null)
alias]
(:foreign-key [node-id] :references nodes [id] :on-delete :cascade)))
(refs
[(ref :unique :not-null)
(file :not-null)
(type :not-null)])))
([(node-id :not-null)
(ref :not-null)
(type :not-null)]
(:foreign-key [node-id] :references nodes [id] :on-delete :cascade)))
(tags
([(node-id :not-null)
tag]
(:foreign-key [node-id] :references nodes [id] :on-delete :cascade)))
(links
([(pos :not-null)
(source :not-null)
(dest :not-null)
(type :not-null)
(properties :not-null)]
(:foreign-key [source] :references nodes [id] :on-delete :cascade)))))
(defconst org-roam-db--table-indices
'((alias-node-id aliases [node-id])
(refs-node-id refs [node-id])
(tags-node-id tags [node-id])))
(defun org-roam-db--init (db)
"Initialize database DB with the correct schema and user version."
(emacsql-with-transaction db
(pcase-dolist (`(,table . ,schema) org-roam-db--table-schemata)
(emacsql db "PRAGMA foreign_keys = ON")
(pcase-dolist (`(,table ,schema) org-roam-db--table-schemata)
(emacsql db [:create-table $i1 $S2] table schema))
(emacsql db (format "PRAGMA user_version = %s" org-roam-db--version))))
(pcase-dolist (`(,index-name ,table ,columns) org-roam-db--table-indices)
(emacsql db [:create-index $i1 :on $i2 $S3] index-name table columns))
(emacsql db (format "PRAGMA user_version = %s" org-roam-db-version))))
(defun org-roam-db--upgrade-maybe (db version)
"Upgrades the database schema for DB, if VERSION is old."
(emacsql-with-transaction db
'ignore
(if (< version org-roam-db--version)
(if (< version org-roam-db-version)
(progn
(org-roam-message (format "Upgrading the Org-roam database from version %d to version %d"
version org-roam-db--version))
(org-roam-db-build-cache t))))
version org-roam-db-version))
(org-roam-db-sync t))))
version)
(defun org-roam-db--close (&optional db)
@ -219,268 +230,216 @@ the current `org-roam-directory'."
(dolist (conn (hash-table-values org-roam-db--connection))
(org-roam-db--close conn)))
;;;; Timer-based updating
(defvar org-roam-db-file-update-timer nil
"Timer for updating the database when dirty.")
(defun org-roam-db-mark-dirty ()
"Mark the Org-roam database as dirty."
(add-to-list 'org-roam-db-dirty (list org-roam-directory org-roam-db-location)
nil #'equal))
(defun org-roam-db-update-cache-on-timer ()
"Update the cache if the database is dirty.
This function is called on `org-roam-db-file-update-timer'."
(pcase-dolist (`(,org-roam-directory ,org-roam-db-location) org-roam-db-dirty)
(org-roam-db-build-cache))
(setq org-roam-db-dirty nil))
;;;; Database API
;;;;; Initialization
(defun org-roam-db--initialized-p ()
"Whether the Org-roam cache has been initialized."
(and (file-exists-p org-roam-db-location)
(> (caar (org-roam-db-query [:select (funcall count) :from titles]))
0)))
(defun org-roam-db--ensure-built ()
"Ensures that Org-roam cache is built."
(unless (org-roam-db--initialized-p)
(error "[Org-roam] your cache isn't built yet! Please run org-roam-db-build-cache")))
;;;;; Clearing
(defun org-roam-db-clear ()
(defun org-roam-db-clear-all ()
"Clears all entries in the Org-roam cache."
(interactive)
(when (file-exists-p org-roam-db-location)
(dolist (table (mapcar #'car org-roam-db--table-schemata))
(org-roam-db-query `[:delete :from ,table]))))
(defun org-roam-db--clear-file (&optional file)
(defun org-roam-db-clear-file (&optional file)
"Remove any related links to the FILE.
This is equivalent to removing the node from the graph."
This is equivalent to removing the node from the graph.
If FILE is nil, clear the current buffer."
(setq file (or file (buffer-file-name (buffer-base-buffer))))
(dolist (table (mapcar #'car org-roam-db--table-schemata))
(org-roam-db-query `[:delete :from ,table
:where (= ,(if (eq table 'links) 'source 'file) $s1)]
file)))
(org-roam-db-query [:delete :from files
:where (= file $s1)]
file))
;;;;; Inserting
(defun org-roam-db--insert-meta (&optional update-p)
"Update the metadata of the current buffer into the cache.
If UPDATE-P is non-nil, first remove the meta for the file in the database."
(let* ((file (or org-roam-file-name (buffer-file-name)))
;;;;; 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."
(let* ((file (buffer-file-name))
(attr (file-attributes file))
(atime (file-attribute-access-time attr))
(mtime (file-attribute-modification-time attr))
(hash (org-roam-db--file-hash)))
(when update-p
(org-roam-db-query [:delete :from files
:where (= file $s1)]
file))
(org-roam-db-query
[:insert :into files
:values $v1]
(list (vector file hash (list :atime atime :mtime mtime))))))
(list (vector file hash atime mtime)))))
(defun org-roam-db--insert-titles (&optional update-p)
"Update the titles of the current buffer into the cache.
If UPDATE-P is non-nil, first remove titles for the file in the database.
Returns the number of rows inserted."
(let* ((file (or org-roam-file-name (buffer-file-name)))
(titles (or (org-roam--extract-titles)
(list (org-roam--path-to-slug file))))
(rows (mapcar (lambda (title)
(vector file title)) titles)))
(when update-p
(org-roam-db-query [:delete :from titles
:where (= file $s1)]
file))
(org-roam-db-query
[:insert :into titles
:values $v1]
rows)
(length rows)))
(defun org-roam-db-get-scheduled-time ()
"Return the scheduled time at point in ISO8601 format."
(when-let ((time (org-get-scheduled-time (point))))
(org-format-time-string "%FT%T%z" time)))
(defun org-roam-db--insert-refs (&optional update-p)
"Update the refs of the current buffer into the cache.
If UPDATE-P is non-nil, first remove the ref for the file in the database."
(let ((file (or org-roam-file-name (buffer-file-name)))
(count 0))
(when update-p
(org-roam-db-query [:delete :from refs
:where (= file $s1)]
file))
(when-let ((refs (org-roam--extract-refs)))
(dolist (ref refs)
(let ((key (cdr ref))
(type (car ref)))
(condition-case nil
(progn
(org-roam-db-query
[:insert :into refs :values $v1]
(list (vector key file type)))
(cl-incf count))
(error
(lwarn '(org-roam) :error
(format "Duplicate ref %s in:\n\nA: %s\nB: %s\n\nskipping..."
key
file
(caar (org-roam-db-query
[:select file :from refs
:where (= ref $v1)]
(vector key))))))))))
count))
(defun org-roam-db-get-deadline-time ()
"Return the deadline time at point in ISO8601 format."
(when-let ((time (org-get-deadline-time (point))))
(org-format-time-string "%FT%T%z" time)))
(defun org-roam-db--insert-links (&optional update-p)
"Update the file links of the current buffer in the cache.
If UPDATE-P is non-nil, first remove the links for the file in the database.
Return the number of rows inserted."
(let ((file (or org-roam-file-name (buffer-file-name))))
(when update-p
(org-roam-db-query [:delete :from links
:where (= source $s1)]
file))
(if-let ((links (org-roam--extract-links)))
(progn
(org-roam-db-query
[:insert :into links
(defun org-roam-db-node-p ()
"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)))
(defun org-roam-db-map-nodes (fns)
"Run FNS over all nodes in the current buffer."
(org-with-point-at 1
(org-map-entries
(lambda ()
(when (org-roam-db-node-p)
(dolist (fn fns)
(funcall fn)))))))
(defun org-roam-db-map-links (fns)
"Run FNS over all links in the current buffer."
(org-with-point-at 1
(org-element-map (org-element-parse-buffer) 'link
(lambda (link)
(dolist (fn fns)
(funcall fn link))))))
(defun org-roam-db-insert-file-node ()
"Insert the file-level node into the Org-roam cache."
(org-with-point-at 1
(when (and (= (org-outline-level) 0)
(org-roam-db-node-p))
(when-let ((id (org-id-get)))
(let* ((file (buffer-file-name (buffer-base-buffer)))
(title (org-link-display-format
(or (cadr (assoc "TITLE" (org-collect-keywords '("title"))
#'string-equal))
(file-relative-name file org-roam-directory))))
(pos (point))
(todo nil)
(priority nil)
(scheduled nil)
(deadline nil)
(level 0)
(aliases (org-entry-get (point) "ROAM_ALIASES"))
(tags org-file-tags)
(refs (org-entry-get (point) "ROAM_REFS"))
(properties (org-entry-properties))
(olp (org-get-outline-path)))
(org-roam-db-query!
(lambda (err)
(lwarn 'org-roam :warning "%s for %s (%s) in %s"
(error-message-string err)
title id file))
[:insert :into nodes
:values $v1]
links)
(length links))
0)))
(defun org-roam-db--insert-ids (&optional update-p)
"Update the ids of the current buffer into the cache.
If UPDATE-P is non-nil, first remove ids for the file in the database.
Returns the number of rows inserted."
(let ((file (or org-roam-file-name (buffer-file-name))))
(when update-p
(org-roam-db-query [:delete :from ids
:where (= file $s1)]
file))
(if-let ((ids (org-roam--extract-ids file)))
(condition-case nil
(progn
(vector id file level pos todo priority
scheduled deadline title properties olp))
(when tags
(org-roam-db-query
[:insert :into ids
[:insert :into tags
:values $v1]
ids)
(length ids))
(error
(lwarn '(org-roam) :error
(format "Duplicate IDs in %s, one of:\n\n%s\n\nskipping..."
(aref (car ids) 1)
(string-join (mapcar (lambda (hl)
(aref hl 0)) ids) "\n")))
0))
0)))
(mapcar (lambda (tag)
(vector id (substring-no-properties tag)))
tags)))
(when aliases
(org-roam-db-query
[:insert :into aliases
:values $v1]
(mapcar (lambda (alias)
(vector id alias))
(split-string-and-unquote aliases))))
(when refs
(setq refs (split-string-and-unquote refs))
(let (rows)
(dolist (ref refs)
(if (string-match org-link-plain-re ref)
(progn
(push (vector id (match-string 2 ref)
(match-string 1 ref)) rows))
(lwarn '(org-roam) :warning
"%s:%s\tInvalid ref %s, skipping..."
(buffer-file-name) (point) ref)))
(when rows
(org-roam-db-query
[:insert :into refs
:values $v1]
rows)))))))))
(defun org-roam-db--insert-tags (&optional update-p)
"Insert tags for the current buffer into the Org-roam cache.
If UPDATE-P is non-nil, first remove tags for the file in the database.
Return the number of rows inserted."
(let* ((file (or org-roam-file-name (buffer-file-name)))
(tags (org-roam--extract-tags file)))
(when update-p
(org-roam-db-query [:delete :from tags
:where (= file $s1)]
file))
(if tags
(progn (org-roam-db-query
[:insert :into tags
:values $v1]
(list (vector file tags)))
1)
0)))
(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)))
(heading-components (org-heading-components))
(pos (point))
(todo (nth 2 heading-components))
(priority (nth 3 heading-components))
(level (nth 1 heading-components))
(scheduled (org-roam-db-get-scheduled-time))
(deadline (org-roam-db-get-deadline-time))
(title (org-link-display-format (nth 4 heading-components)))
(properties (org-entry-properties))
(olp (org-get-outline-path)))
(org-roam-db-query!
(lambda (err)
(lwarn 'org-roam :warning "%s for %s (%s) in %s"
(error-message-string err)
title id file))
[:insert :into nodes
:values $v1]
(vector id file level pos todo priority
scheduled deadline title properties olp)))))
(defun org-roam-db-insert-aliases ()
"Insert aliases for node at point into Org-roam cache."
(when-let ((node-id (org-id-get))
(aliases (org-entry-get (point) "ROAM_ALIASES")))
(org-roam-db-query [:insert :into aliases
:values $v1]
(mapcar (lambda (alias)
(vector node-id alias))
(split-string-and-unquote aliases)))))
(defun org-roam-db-insert-tags ()
"Insert tags for node at point into Org-roam cache."
(when-let ((node-id (org-id-get))
(tags (org-get-tags)))
(org-roam-db-query [:insert :into tags
:values $v1]
(mapcar (lambda (tag)
(vector node-id (substring-no-properties tag))) tags))))
(defun org-roam-db-insert-refs ()
"Insert refs for node at point into Org-roam cache."
(when-let* ((node-id (org-id-get))
(refs (org-entry-get (point) "ROAM_REFS"))
(refs (split-string-and-unquote refs)))
(let (rows)
(dolist (ref refs)
(save-match-data
(if (string-match org-link-plain-re ref)
(progn
(push (vector node-id (match-string 2 ref) (match-string 1 ref)) rows))
(lwarn '(org-roam) :warning
"%s:%s\tInvalid ref %s, skipping..." (buffer-file-name) (point) ref))))
(org-roam-db-query [:insert :into refs
:values $v1]
rows))))
(defun org-roam-db-insert-link (link)
"Insert link data for LINK at current point into the Org-roam cache."
(save-excursion
(goto-char (org-element-property :begin link))
(let ((type (org-element-property :type link))
(dest (org-element-property :path link))
(properties (list :outline (org-get-outline-path)))
(source (org-roam-id-at-point)))
(when source
(org-roam-db-query
[:insert :into links
:values $v1]
(vector (point) source dest type properties))))))
;;;;; Fetching
(defun org-roam-db-has-file-p (file)
"Return t if FILE is in the database, nil otherwise."
(> (caar (org-roam-db-query [:select (funcall count) :from files
:where (= file $s1)]
file))
0))
(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 * :from files]))
(ht (make-hash-table :test #'equal)))
(let ((current-files (org-roam-db-query [:select [file hash] :from files]))
(ht (make-hash-table :test #'equal)))
(dolist (row current-files)
(puthash (car row) (cadr row) ht))
ht))
(defun org-roam-db--get-title (file)
"Return the main title of FILE from the cache."
(caar (org-roam-db-query [:select [title] :from titles
:where (= file $s1)
:limit 1]
file)))
(defun org-roam-db--get-tags ()
"Return all distinct tags from the cache."
(let ((rows (org-roam-db-query [:select :distinct [tags] :from tags]))
acc)
(dolist (row rows)
(dolist (tag (car row))
(unless (member tag acc)
(push tag acc))))
acc))
(defun org-roam-db--connected-component (file)
"Return all files reachable from/connected to FILE, including the file itself.
If the file does not have any connections, nil is returned."
(let* ((query "WITH RECURSIVE
links_of(file, link) AS
(WITH filelinks AS (SELECT * FROM links WHERE NOT \"type\" = '\"cite\"'),
citelinks AS (SELECT * FROM links
JOIN refs ON links.\"dest\" = refs.\"ref\"
AND links.\"type\" = '\"cite\"')
SELECT \"source\", \"dest\" FROM filelinks UNION
SELECT \"dest\", \"source\" FROM filelinks UNION
SELECT \"file\", \"source\" FROM citelinks UNION
SELECT \"dest\", \"file\" FROM citelinks),
connected_component(file) AS
(SELECT link FROM links_of WHERE file = $s1
UNION
SELECT link FROM links_of JOIN connected_component USING(file))
SELECT * FROM connected_component;")
(files (mapcar 'car-safe (emacsql (org-roam-db) query file))))
files))
(defun org-roam-db--links-with-max-distance (file max-distance)
"Return all files connected to FILE in at most MAX-DISTANCE steps.
This includes the file itself. If the file does not have any
connections, nil is returned."
(let* ((query "WITH RECURSIVE
links_of(file, link) AS
(WITH filelinks AS (SELECT * FROM links WHERE NOT \"type\" = '\"cite\"'),
citelinks AS (SELECT * FROM links
JOIN refs ON links.\"dest\" = refs.\"ref\"
AND links.\"type\" = '\"cite\"')
SELECT \"source\", \"dest\" FROM filelinks UNION
SELECT \"dest\", \"source\" FROM filelinks UNION
SELECT \"file\", \"source\" FROM citelinks UNION
SELECT \"source\", \"file\" FROM citelinks),
-- Links are traversed in a breadth-first search. In order to calculate the
-- distance of nodes and to avoid following cyclic links, the visited nodes
-- are tracked in 'trace'.
connected_component(file, trace) AS
(VALUES($s1, json_array($s1))
UNION
SELECT lo.link, json_insert(cc.trace, '$[' || json_array_length(cc.trace) || ']', lo.link) FROM
connected_component AS cc JOIN links_of AS lo USING(file)
WHERE (
-- Avoid cycles by only visiting each file once.
(SELECT count(*) FROM json_each(cc.trace) WHERE json_each.value == lo.link) == 0
-- Note: BFS is cut off early here.
AND json_array_length(cc.trace) < ($s2 + 1)))
SELECT DISTINCT file, min(json_array_length(trace)) AS distance
FROM connected_component GROUP BY file ORDER BY distance;")
;; In principle the distance would be available in the second column.
(files (mapcar 'car-safe (emacsql (org-roam-db) query file max-distance))))
files))
(defun org-roam-db--file-hash (&optional file-path)
"Compute the hash of FILE-PATH, a file or current buffer."
(if file-path
@ -492,30 +451,9 @@ connections, nil is returned."
(secure-hash 'sha1 (current-buffer)))))
;;;;; Updating
(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))))
(if (not (file-exists-p file-path))
(org-roam-db--clear-file file-path)
;; save the file before performing a database update
(when-let ((buf (find-buffer-visiting file-path)))
(with-current-buffer buf
(save-buffer)))
(org-roam--with-temp-buffer file-path
(emacsql-with-transaction (org-roam-db)
(org-roam-db--insert-meta 'update)
(org-roam-db--insert-tags 'update)
(org-roam-db--insert-titles 'update)
(org-roam-db--insert-refs 'update)
(when org-roam-enable-headline-linking
(org-roam-db--insert-ids 'update))
(org-roam-db--insert-links 'update)))))
(defun org-roam-db-build-cache (&optional force)
"Build the cache for `org-roam-directory'.
;;;###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")
(when force (delete-file org-roam-db-location))
@ -525,109 +463,61 @@ If FORCE, force a rebuild of the cache from scratch."
(org-agenda-files nil)
(org-roam-files (org-roam--list-all-files))
(current-files (org-roam-db--get-current-files))
(count-plist nil)
(deleted-count 0)
(modified-files nil))
(dolist (file org-roam-files)
(let ((contents-hash (org-roam-db--file-hash file)))
(unless (string= (gethash file current-files)
contents-hash)
(push (cons file contents-hash) modified-files)))
contents-hash)
(push file modified-files)))
(remhash file current-files))
(dolist (file (hash-table-keys current-files))
;; These files are no longer around, remove from cache...
(org-roam-db--clear-file file)
(setq deleted-count (1+ deleted-count)))
(setq count-plist (org-roam-db--update-files modified-files))
(org-roam-message "total: Δ%s, files-modified: Δ%s, ids: Δ%s, links: Δ%s, tags: Δ%s, titles: Δ%s, refs: Δ%s, deleted: Δ%s"
(- (length org-roam-files) (plist-get count-plist :error-count))
(plist-get count-plist :modified-count)
(plist-get count-plist :id-count)
(plist-get count-plist :link-count)
(plist-get count-plist :tag-count)
(plist-get count-plist :title-count)
(plist-get count-plist :ref-count)
deleted-count)))
(emacsql-with-transaction (org-roam-db)
(if (fboundp 'dolist-with-progress-reporter)
(dolist-with-progress-reporter (file (hash-table-keys current-files))
"Clearing removed files..."
(org-roam-db-clear-file file))
(dolist (file (hash-table-keys current-files))
(org-roam-db-clear-file file)))
(if (fboundp 'dolist-with-progress-reporter)
(dolist-with-progress-reporter (file modified-files)
"Processing modified files..."
(org-roam-db-update-file file))
(dolist (file modified-files)
(org-roam-db-update-file file))))))
(defun org-roam-db--get-file-hash-from-db (&optional file-path)
"Get hash from Org-roam database for FILE-PATH."
(setq file-path (or file-path
(buffer-file-name (buffer-base-buffer))))
(caar (org-roam-db-query [:select hash :from files
:where (= file $s1)] file-path)))
(defun org-roam-db-update-file (file-path)
(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 (org-roam-db--get-file-hash-from-db 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-db--update-files (list (cons file-path content-hash)))
(org-roam-message "Updated: %s" file-path))))
(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)))))))
(defun org-roam-db--update-files (modified-files)
"Update Org-roam cache for a list of MODIFIED-FILES.
FILES is a list of (file . hash) pairs."
(let* ((gc-cons-threshold org-roam-db-gc-threshold)
(org-agenda-files nil)
(error-count 0)
(id-count 0)
(link-count 0)
(tag-count 0)
(title-count 0)
(ref-count 0)
(modified-count 0))
(pcase-dolist (`(,file . _) modified-files)
(org-roam-db--clear-file file))
;; Process all the files for IDs first
;;
;; We do this so that link extraction is cheaper: this eliminates the need
;; to read the file to check if the ID really exists
(pcase-dolist (`(,file . ,contents-hash) modified-files)
(let* ((attr (file-attributes file))
(atime (file-attribute-access-time attr))
(mtime (file-attribute-modification-time attr)))
(condition-case nil
(org-roam--with-temp-buffer file
(org-roam-db-query
[:insert :into files
:values $v1]
(vector file contents-hash (list :atime atime :mtime mtime)))
(when org-roam-enable-headline-linking
(setq id-count (+ id-count (org-roam-db--insert-ids)))))
(file-error
(setq error-count (1+ error-count))
(org-roam-db--clear-file file)
(lwarn '(org-roam) :warning
"Skipping unreadable file while building cache: %s" file)))))
(defun org-roam-db--update-on-save-h ()
"."
(add-hook 'after-save-hook #'org-roam-db-update-file nil t))
;; Process titles, tags, links and ref links of file
(pcase-dolist (`(,file . _) modified-files)
(org-roam-message "Processed %s/%s modified files..." modified-count (length modified-files))
(condition-case nil
(org-roam--with-temp-buffer file
(setq modified-count (1+ modified-count))
(setq link-count (+ link-count (org-roam-db--insert-links)))
(setq tag-count (+ tag-count (org-roam-db--insert-tags)))
(setq title-count (+ title-count (org-roam-db--insert-titles)))
(setq ref-count (+ ref-count (org-roam-db--insert-refs))))
(file-error
(setq error-count (1+ error-count))
(org-roam-db--clear-file file)
(lwarn '(org-roam) :warning
"Skipping unreadable file while building cache: %s" file))))
(list :error-count error-count :modified-count modified-count :id-count id-count :title-count title-count :tag-count tag-count :link-count link-count :ref-count ref-count)))
(add-hook 'org-roam-find-file-hook #'org-roam-db--update-on-save-h)
(defun org-roam-db-update ()
"Update the database."
(pcase org-roam-db-update-method
('immediate
(org-roam-db-update-file (buffer-file-name (buffer-base-buffer))))
('idle-timer
(org-roam-db-mark-dirty))
(_
(user-error "Invalid `org-roam-db-update-method'"))))
;; Diagnostic Interactives
(defun org-roam-db-diagnose-node ()
"Print information about node at point."
(interactive)
(prin1 (org-roam-node-at-point)))
(provide 'org-roam-db)

46
org-roam-dev.el
View File

@ -1,46 +0,0 @@
;;; org-roam-dev.el --- Org-roam development code -mode -*- 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: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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 code for org-roam developers.
;; It is intended to be loaded before editing org-roam source files.
;; It ensures consistent application of various developer settings.
;;
;;; Code:
(require 'emacsql)
;;;###autoload
(define-minor-mode org-roam-dev-mode
"Minor mode for setting the dev environment of Org-roam."
:lighter " ORD"
(when org-roam-dev-mode
(emacsql-fix-vector-indentation)
(setq-local sentence-end-double-space nil)))
(provide 'org-roam-dev)
;;; org-roam-dev.el ends here

318
org-roam-doctor.el
View File

@ -1,318 +0,0 @@
;;; org-roam-doctor.el --- Linter for Org-roam files -*- coding: utf-8; lexical-binding: t; -*-
;;
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/jethrokuan/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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 `org-roam-doctor', a utility for diagnosing and fixing
;; Org-roam files. Running `org-roam-doctor' launches a list of checks defined
;; by `org-roam-doctor--checkers'. Every checker is an instance of
;; `org-roam-doctor-checker'.
;;
;; Each checker is given the Org parse tree (AST), and is expected to return a
;; list of errors. The checker can also provide "actions" for auto-fixing errors
;; (see `org-roam-doctor--remove-link' for an example).
;;
;; The UX experience is inspired by both org-lint and checkdoc, and their code
;; is heavily referenced.
;;
;;; Code:
;; Library Requires
(require 'cl-lib)
(require 'org)
(require 'org-element)
(require 's)
(require 'dash)
(require 'org-roam-macs)
(declare-function org-roam-insert "org-roam")
(declare-function org-roam--get-roam-buffers "org-roam")
(declare-function org-roam--list-all-files "org-roam")
(declare-function org-roam--org-roam-file-p "org-roam")
(declare-function org-roam-mode "org-roam")
(defvar org-roam-verbose)
(defvar org-roam-mode)
(defcustom org-roam-doctor-inhibit-startup t
"Inhibit `org-mode' startup when processing files with `org-doctor'.
When non-nil, images and LaTeX preview will not be generated,
tables will not be aligned, and headlines will not respect
startup visability. This significantly improves performance when
processing multiple files"
:type 'boolean
:group 'org-roam)
(cl-defstruct (org-roam-doctor-checker (:copier nil))
(name 'missing-checker-name)
(description "")
(actions nil))
(defconst org-roam-doctor--checkers
(list
(make-org-roam-doctor-checker
:name 'org-roam-doctor-broken-links
:description "Fix broken links."
:actions '(("d" . ("Unlink" . org-roam-doctor--remove-link))
("r" . ("Replace link" . org-roam-doctor--replace-link))
("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
(make-org-roam-doctor-checker
:name 'org-roam-doctor-check-roam-props
:description "Check #+roam_* properties.")
(make-org-roam-doctor-checker
:name 'org-roam-doctor-check-tags
:description "Check #+roam_tags.")
(make-org-roam-doctor-checker
:name 'org-roam-doctor-check-alias
:description "Check #+roam_alias.")))
(defconst org-roam-doctor--supported-roam-properties
'("roam_tags" "roam_alias" "roam_key")
"List of supported Org-roam properties.")
(defun org-roam-doctor-check-roam-props (ast)
"Checker for detecting invalid #+roam_* properties.
AST is the org-element parse tree."
(let (reports)
(org-element-map ast 'keyword
(lambda (kw)
(let ((key (org-element-property :key kw)))
(when (and (string-prefix-p "ROAM_" key t)
(not (member (downcase key) org-roam-doctor--supported-roam-properties)))
(push
`(,(org-element-property :begin kw)
,(concat "Possible mispelled key: "
(prin1-to-string key)
"\nOrg-roam supports the following keys: "
(s-join ", " org-roam-doctor--supported-roam-properties)))
reports)))))
reports))
(defun org-roam-doctor-check-tags (ast)
"Checker for detecting invalid #+roam_tags.
AST is the org-element parse tree."
(let (reports)
(org-element-map ast 'keyword
(lambda (kw)
(when (string-collate-equalp (org-element-property :key kw) "roam_tags" nil t)
(let ((tags (org-element-property :value kw)))
(condition-case nil
(split-string-and-unquote tags)
(error
(push
`(,(org-element-property :begin kw)
,(concat "Unable to parse tags: "
tags
(when (s-contains? "," tags)
"\nCheck that your tags are not comma-separated.")))
reports)))))))
reports))
(defun org-roam-doctor-check-alias (ast)
"Checker for detecting invalid #+roam_alias.
AST is the org-element parse tree."
(let (reports)
(org-element-map ast 'keyword
(lambda (kw)
(when (string-collate-equalp (org-element-property :key kw) "roam_alias" nil t)
(let ((aliases (org-element-property :value kw)))
(condition-case nil
(split-string-and-unquote aliases)
(error
(push
`(,(org-element-property :begin kw)
,(concat "Unable to parse aliases: "
aliases
(when (s-contains? "," aliases)
"\nCheck that your aliases are not comma-separated.")))
reports)))))))
reports))
(defun org-roam-doctor-broken-links (ast)
"Checker for detecting broken links.
AST is the org-element parse tree."
(let (reports)
(org-element-map ast 'link
(lambda (l)
(when (equal "file" (org-element-property :type l))
(let ((file (org-element-property :path l)))
(or (file-exists-p file)
(file-remote-p file)
(push
`(,(org-element-property :begin l)
,(format (if (org-element-lineage l '(link))
"Link to non-existent image file \"%s\"\
in link description"
"Link to non-existent local file \"%s\"")
file))
reports))))))
reports))
(defun org-roam-doctor--check (buffer checkers)
"Check BUFFER for errors.
CHECKERS is the list of checkers used."
(with-current-buffer buffer
(save-excursion
(goto-char (point-min))
(let* ((ast (org-element-parse-buffer))
(errors (sort (cl-mapcan
(lambda (c)
(mapcar
(lambda (report)
(list (set-marker (make-marker) (car report))
(nth 1 report) c))
(save-excursion
(funcall
(org-roam-doctor-checker-name c)
ast))))
checkers)
#'car-less-than-car)))
(dolist (e errors)
(pcase-let ((`(,m ,msg ,checker) e))
(switch-to-buffer buffer)
(goto-char m)
(org-reveal)
(undo-boundary)
(org-roam-doctor--resolve msg checker)
(set-marker m nil)))
errors))))
;;; Actions
(defun org-roam-doctor--recursive-edit ()
"Launch into a recursive edit."
(message "When you're done editing press C-M-c to continue.")
(recursive-edit))
(defun org-roam-doctor--skip ()
"Skip the current error."
(org-roam-message "Skipping..."))
(defun org-roam-doctor--replace-link ()
"Replace the current link with a new link."
(save-match-data
(unless (org-in-regexp org-link-bracket-re 1)
(user-error "No link at point"))
(let ((orig (buffer-string))
(p (point)))
(condition-case nil
(save-excursion
(replace-match "")
(org-roam-insert))
(quit (progn
(replace-buffer-contents orig)
(goto-char p)))))))
(defun org-roam-doctor--replace-link-keep-label ()
"Replace the current link with a new link, keeping the current link's label."
(save-match-data
(unless (org-in-regexp org-link-bracket-re 1)
(user-error "No link at point"))
(let ((orig (buffer-string))
(p (point)))
(condition-case nil
(save-excursion
(let ((label (if (match-end 2)
(match-string-no-properties 2)
(org-link-unescape (match-string-no-properties 1)))))
(replace-match "")
(org-roam-insert nil nil label)))
(quit (progn
(replace-buffer-contents orig)
(goto-char p)))))))
(defun org-roam-doctor--remove-link ()
"Unlink the text at point."
(unless (org-in-regexp org-link-bracket-re 1)
(user-error "No link at point"))
(save-excursion
(let ((label (if (match-end 2)
(match-string-no-properties 2)
(org-link-unescape (match-string-no-properties 1)))))
(delete-region (match-beginning 0) (match-end 0))
(insert label))))
(defun org-roam-doctor--resolve (msg checker)
"Resolve an error.
MSG is the error that was found, which is displayed in a help buffer.
CHECKER is a org-roam-doctor checker instance."
(let ((actions (org-roam-doctor-checker-actions checker))
c)
(push '("e" . ("Edit" . org-roam-doctor--recursive-edit)) actions)
(push '("s" . ("Skip" . org-roam-doctor--skip)) actions)
(with-output-to-temp-buffer "*Org-roam-doctor Help*"
(mapc #'princ
(list "Error message:\n " msg "\n\n"))
(dolist (action actions)
(princ (format "[%s]: %s\n"
(car action)
(cadr action))))
(princ "\n\n"))
(shrink-window-if-larger-than-buffer
(get-buffer-window "*Org-roam-doctor Help*"))
(message "Press key for command:")
(unwind-protect
(progn
(cl-loop
do (setq c (char-to-string (read-char-exclusive)))
until (assoc c actions)
do (message "Please enter a valid key for command:"))
(funcall (cddr (assoc c actions)))
(redisplay))
(when (get-buffer-window "*Org-roam-doctor Help*")
(delete-window (get-buffer-window "*Org-roam-doctor Help*"))
(kill-buffer "*Org-roam-doctor Help*")))))
;;;###autoload
(defun org-roam-doctor (&optional checkall)
"Perform a check on the current buffer to ensure cleanliness.
If CHECKALL, run the check for all Org-roam files."
(interactive "P")
(unless org-roam-mode (org-roam-mode))
(let ((files (if checkall
(org-roam--list-all-files)
(unless (org-roam--org-roam-file-p)
(user-error "Not in an org-roam file"))
`(,(buffer-file-name)))))
(org-roam-doctor-start files org-roam-doctor--checkers)))
(defun org-roam-doctor-start (files checkers)
"Lint FILES using CHECKERS."
(save-window-excursion
(let ((existing-buffers (org-roam--get-roam-buffers))
(org-inhibit-startup org-roam-doctor-inhibit-startup))
(dolist (f files)
(let ((buf (find-file-noselect f)))
(org-roam-doctor--check buf checkers)
(unless (memq buf existing-buffers)
(with-current-buffer buf
(save-buffer))
(kill-buffer buf))))))
(org-roam-message "Linting completed."))
(provide 'org-roam-doctor)
;;; org-roam-doctor.el ends here

77
org-roam-faces.el
View File

@ -1,77 +0,0 @@
;;; org-roam-faces.el --- Face definitions -*- 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: 1.2.3
;; Package-Requires: ((emacs "26.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 file contains the face definitions for Org-roam.
;;; Code:
(defgroup org-roam-faces nil
"Faces used by Org-roam."
:group 'org-roam
:group 'faces)
;;; Definitions
(defface org-roam-link
'((t :inherit org-link))
"Face for Org-roam links."
:group 'org-roam-faces)
(defface org-roam-tag
'((t :weight bold))
"Face for Org-roam tags in minibuffer commands."
:group 'org-roam-faces)
(defface org-roam-link-current
'((t :inherit org-link))
"Face for Org-roam links pointing to the current buffer."
:group 'org-roam-faces)
(defface org-roam-link-invalid
'((t :inherit (error org-link)))
"Face for Org-roam links that are not valid.
This face is used for links without a destination."
:group 'org-roam-faces)
(defface org-roam-link-shielded
'((t :inherit (warning org-link)))
"Face for Org-roam links that are shielded.
This face is used on the region target by `org-roam-insertion'
during an `org-roam-capture'."
:group 'org-roam-faces)
(defface org-roam-dailies-calendar-note
'((t :inherit (org-roam-link) :underline nil))
"Face for dates with a daily-note in the calendar."
:group 'org-roam-faces)
;;; _
(provide 'org-roam-faces)
;;; org-roam-faces.el ends here

306
org-roam-graph.el
View File

@ -1,12 +1,12 @@
;;; org-roam-graph.el --- Graphing API -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
;; 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: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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.
@ -31,17 +31,12 @@
;;
;;; Code:
(require 'xml) ;xml-escape-string
(require 's) ;s-truncate, s-replace
(eval-and-compile
(require 'org-roam-macs))
(require 'org-roam-db)
;;;; Declarations
(defvar org-roam-directory)
(defvar org-roam-mode)
(declare-function org-roam--org-roam-file-p "org-roam")
(declare-function org-roam--path-to-slug "org-roam")
(declare-function org-roam-mode "org-roam")
;;;; Options
(defcustom org-roam-graph-viewer (executable-find "firefox")
@ -74,31 +69,34 @@ Example:
:type '(alist)
:group 'org-roam)
(defcustom org-roam-graph-edge-extra-config nil
"Extra edge options passed to graphviz.
Example:
'((\"dir\" . \"back\"))"
:type '(alist)
:group 'org-roam)
(defcustom org-roam-graph-node-extra-config
'(("shape" . "underline")
("style" . "rounded,filled")
("fillcolor" . "#EEEEEE")
("color" . "#C9C9C9")
("fontcolor" . "#111111"))
"Extra options for graphviz nodes.
Example:
'((\"color\" . \"skyblue\"))"
'(("id" . (("style" . "bold,rounded,filled")
("fillcolor" . "#EEEEEE")
("color" . "#C9C9C9")
("fontcolor" . "#111111")))
("http" . (("style" . "rounded,filled")
("fillcolor" . "#EEEEEE")
("color" . "#C9C9C9")
("fontcolor" . "#0A97A6")))
("https" . (("shape" . "rounded,filled")
("fillcolor" . "#EEEEEE")
("color" . "#C9C9C9")
("fontcolor" . "#0A97A6"))))
"Extra options for graphviz nodes."
:type '(alist)
:group 'org-roam)
(defcustom org-roam-graph-edge-extra-config
'(("color" . "#333333"))
"Extra options for graphviz edges.
Example:
'((\"dir\" . \"back\"))"
:type '(alist)
:group 'org-roam)
(defcustom org-roam-graph-edge-cites-extra-config '(("color" . "red"))
"Extra options for graphviz edges for citation links.
Example:
'((\"dir\" . \"back\"))"
:type '(alist)
(defcustom org-roam-graph-link-hidden-types
'("file")
"What sort of links to hide from the Org-roam graph."
:type '(repeat string)
:group 'org-roam)
(defcustom org-roam-graph-max-title-length 100
@ -119,45 +117,6 @@ All other values including nil will have no effect."
(const :tag "no" nil))
:group 'org-roam)
(defcustom org-roam-graph-exclude-matcher nil
"Matcher for excluding nodes from the generated graph.
Any nodes and links for file paths matching this string is
excluded from the graph.
If value is a string, the string is the only matcher.
If value is a list, all file paths matching any of the strings
are excluded."
:type '(choice
(string :tag "Matcher")
(list :tag "Matchers"))
:group 'org-roam)
;;;; Functions
(defun org-roam-graph--expand-matcher (col &optional negate where)
"Return the exclusion regexp from `org-roam-graph-exclude-matcher'.
COL is the symbol to be matched against. if NEGATE, add :not to sql query.
set WHERE to true if WHERE query already exists."
(let ((matchers (pcase org-roam-graph-exclude-matcher
('nil nil)
((pred stringp) `(,(concat "%" org-roam-graph-exclude-matcher "%")))
((pred listp) (mapcar (lambda (m)
(concat "%" m "%"))
org-roam-graph-exclude-matcher))
(_ (error "Invalid org-roam-graph-exclude-matcher"))))
res)
(dolist (match matchers)
(if where
(push :and res)
(push :where res)
(setq where t))
(push col res)
(when negate
(push :not res))
(push :like res)
(push match res))
(nreverse res)))
(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.
@ -166,71 +125,104 @@ If WRAP-VAL is non-nil it wraps the VAL."
"="
wrap-val (cdr option) wrap-val))
(defun org-roam-graph--dot (node-query)
"Build the graphviz dot string for NODE-QUERY.
The Org-roam database titles table is read, to obtain the list of titles.
The links table is then read to obtain all directed links, and formatted
into a digraph."
(org-roam-db--ensure-built)
(org-roam--with-temp-buffer nil
(let* ((nodes (org-roam-db-query node-query))
(edges-query
`[:with selected :as [:select [file] :from ,node-query]
:select :distinct [dest source] :from links
:where (and (in dest selected) (in source selected))])
(edges-cites-query
`[:with selected :as [:select [file] :from ,node-query]
:select :distinct [file source]
:from links :inner :join refs :on (and (= links:dest refs:ref)
(= links:type "cite")
(= refs:type "cite"))
:where (and (in file selected) (in source selected))])
(edges (org-roam-db-query edges-query))
(edges-cites (org-roam-db-query edges-cites-query)))
(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 (org-roam--nodes-table))
(seen-nodes (list))
(edges (or edges (org-roam-db-query [:select :distinct [source dest type] :from links]))))
(with-temp-buffer
(setq-local org-roam-directory org-roam-directory-temp)
(insert "digraph \"org-roam\" {\n")
(dolist (option org-roam-graph-extra-config)
(insert (org-roam-graph--dot-option option) ";\n"))
(dolist (attribute '("node" "edge"))
(insert (format " %s [%s];\n" attribute
(mapconcat (lambda (var)
(org-roam-graph--dot-option var nil "\""))
(symbol-value
(intern (concat "org-roam-graph-" attribute "-extra-config")))
","))))
(dolist (node nodes)
(let* ((file (xml-escape-string (car node)))
(title (or (cadr node)
(org-roam--path-to-slug file)))
(shortened-title (pcase org-roam-graph-shorten-titles
(`truncate (s-truncate org-roam-graph-max-title-length title))
(`wrap (s-word-wrap org-roam-graph-max-title-length title))
(_ title)))
(shortened-title (org-roam-string-quote shortened-title))
(title (org-roam-string-quote title))
(node-properties
`(("label" . ,shortened-title)
("URL" . ,(concat "org-protocol://roam-file?file=" (url-hexify-string file)))
("tooltip" . ,(xml-escape-string title)))))
(insert
(format " \"%s\" [%s];\n" file
(mapconcat (lambda (n)
(org-roam-graph--dot-option n nil "\""))
node-properties ",")))))
(dolist (edge edges)
(insert (apply #'format `(" \"%s\" -> \"%s\";\n"
,@(mapcar #'xml-escape-string edge)))))
(insert (format " edge [%s];\n"
(mapconcat #'org-roam-graph--dot-option
org-roam-graph-edge-cites-extra-config ",")))
(dolist (edge edges-cites)
(insert (apply #'format `(" \"%s\" -> \"%s\";\n"
,@(mapcar #'xml-escape-string edge)))))
(insert (format " edge [%s];\n"
(mapconcat (lambda (var)
(org-roam-graph--dot-option var nil "\""))
org-roam-graph-edge-extra-config
",")))
(pcase-dolist (`(,source ,dest ,type) edges)
(unless (member type org-roam-graph-link-hidden-types)
(pcase-dolist (`(,node ,node-type) `((,source "id")
(,dest ,type)))
(unless (member node seen-nodes)
(insert (org-roam-graph--format-node
(or (gethash node nodes-table) node) node-type))
(push node seen-nodes)))
(insert (format " \"%s\" -> \"%s\";\n"
(xml-escape-string source)
(xml-escape-string dest)))))
(when all-nodes
(maphash (lambda (id node)
(unless (member id seen-nodes)
(insert (org-roam-graph--format-node node "id"))))
nodes-table))
(insert "}")
(buffer-string))))
(defun org-roam-graph--build (&optional node-query callback)
"Generate a graph showing the relations between nodes in NODE-QUERY.
Execute CALLBACK when process exits successfully.
(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 (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="
(url-hexify-string (org-roam-node-id node))))
("tooltip" . ,(xml-escape-string title)))))
(setq node-id node
node-properties (append `(("label" . ,(concat type ":" node)))
(when (member type (list "http" "https"))
`(("URL" . ,(xml-escape-string (concat type ":" node))))))))
(format "\"%s\" [%s];\n"
node-id
(mapconcat (lambda (n)
(org-roam-graph--dot-option n nil "\""))
(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"))
@ -238,12 +230,7 @@ CALLBACK is passed the graph file as its sole argument."
(user-error (concat "Cannot find executable \"%s\" to generate the graph. "
"Please adjust `org-roam-graph-executable'")
org-roam-graph-executable))
(let* ((node-query (or node-query
`[:select [file title] :from titles
,@(org-roam-graph--expand-matcher 'file t)
:group :by file]))
(graph (org-roam-graph--dot node-query))
(temp-dot (make-temp-file "graph." nil ".dot" graph))
(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
@ -268,47 +255,26 @@ CALLBACK is passed the graph file as its sole argument."
('nil (view-file file))
(_ (signal 'wrong-type-argument `((functionp stringp null) ,org-roam-graph-viewer)))))
(defun org-roam-graph--build-connected-component (file &optional max-distance callback)
"Build a graph of nodes connected to FILE.
If MAX-DISTANCE is non-nil, limit nodes to MAX-DISTANCE steps.
CALLBACK is passed to `org-roam-graph--build'."
(let* ((file (expand-file-name file))
(files (or (if (and max-distance (>= max-distance 0))
(org-roam-db--links-with-max-distance file max-distance)
(org-roam-db--connected-component file))
(list file)))
(query `[:select [file title]
:from titles
:where (in file [,@files])]))
(org-roam-graph--build query callback)))
;;;; Commands
;;;###autoload
(defun org-roam-graph (&optional arg file node-query)
"Build and possibly display a graph for FILE from NODE-QUERY.
If FILE is nil, default to current buffer's file name.
(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 FILE.
- `\\[universal-argument]' N show the graph for FILE limiting nodes to N steps.
- `\\[universal-argument] \\[universal-argument]' build the graph.
- `\\[universal-argument]' - build the graph for FILE.
- `\\[universal-argument]' -N build the graph for FILE limiting nodes to N steps."
(interactive "P")
(unless org-roam-mode (org-roam-mode))
(let ((file (or file (buffer-file-name (buffer-base-buffer)))))
(unless (or (not arg) (equal arg '(16)))
(unless file
(user-error "Cannot build graph for nil file. Is current buffer visiting a file?"))
(unless (org-roam--org-roam-file-p file)
(user-error "\"%s\" is not an org-roam file" file)))
(pcase arg
('nil (org-roam-graph--build node-query #'org-roam-graph--open))
('(4) (org-roam-graph--build-connected-component file nil #'org-roam-graph--open))
((pred integerp) (org-roam-graph--build-connected-component file (abs arg) (when (>= arg 0) #'org-roam-graph--open)))
('(16) (org-roam-graph--build node-query))
('- (org-roam-graph--build-connected-component file))
(_ (user-error "Unrecognized ARG: %s" arg)))))
- `\\[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)

324
org-roam-link.el
View File

@ -1,324 +0,0 @@
;;; org-roam-link.el --- Custom links for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
;; Alan Carroll
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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 adds the custom `roam:' link to Org-roam. `roam:' links allow linking to
;; Org-roam files via their titles and headlines.
;;
;;; Code:
;;;; Dependencies
(require 'ol)
(require 'org-roam-compat)
(require 'org-roam-macs)
(require 'org-roam-db)
(require 'org-element)
(defvar org-roam-completion-ignore-case)
(defvar org-roam-directory)
(declare-function org-roam--find-file "org-roam")
(declare-function org-roam-find-file "org-roam")
(declare-function org-roam-format-link "org-roam")
(defcustom org-roam-link-auto-replace t
"When non-nil, replace Org-roam's roam links with file/id equivalents."
:group 'org-roam
:type 'boolean)
(defcustom org-roam-link-file-path-type 'relative
"How the path name in file links should be stored.
Valid values are:
relative Relative to the current directory, i.e. the directory of the file
into which the link is being inserted.
absolute Absolute path, if possible with ~ for home directory.
noabbrev Absolute path, no abbreviation of home directory."
:group 'org-roam
:type '(choice
(const relative)
(const absolute)
(const noabbrev))
:safe #'symbolp)
;;; the roam: link
(org-link-set-parameters "roam"
:follow #'org-roam-link-follow-link)
(defun org-roam-link-follow-link (_path)
"Navigates to location in Org-roam link.
This function is called by Org when following links of the type
`roam'. While the path is passed, assume that the cursor is on
the link."
(pcase-let ((`(,link-type ,loc ,desc ,mkr) (org-roam-link--get-location)))
(when (and org-roam-link-auto-replace loc desc)
(org-roam-link--replace-link link-type loc desc))
(pcase link-type
("file"
(if loc
(org-roam--find-file loc)
(org-roam-find-file desc nil nil t)))
("id"
(org-goto-marker-or-bmk mkr)))))
;;; Retrieval Functions
(defun org-roam-link--get-titles ()
"Return all titles within Org-roam."
(mapcar #'car (org-roam-db-query [:select [titles:title] :from titles])))
(defun org-roam-link--get-headlines (&optional file with-marker use-stack)
"Return all outline headings for the current buffer.
If FILE, return outline headings for passed FILE instead.
If WITH-MARKER, return a cons cell of (headline . marker).
If USE-STACK, include the parent paths as well."
(org-roam-with-file file (when with-marker 'keep)
(let* ((outline-level-fn outline-level)
(path-separator "/")
(stack-level 0)
stack cands name level marker)
(save-excursion
(goto-char (point-min))
(while (re-search-forward org-complex-heading-regexp nil t)
(save-excursion
(setq name (substring-no-properties (or (match-string 4) "")))
(setq marker (point-marker))
(when use-stack
(goto-char (match-beginning 0))
(setq level (funcall outline-level-fn))
;; Update stack. The empty entry guards against incorrect
;; headline hierarchies, e.g. a level 3 headline
;; immediately following a level 1 entry.
(while (<= level stack-level)
(pop stack)
(cl-decf stack-level))
(while (> level stack-level)
(push name stack)
(cl-incf stack-level))
(setq name (mapconcat #'identity
(reverse stack)
path-separator)))
(push (if with-marker
(cons name marker)
name) cands))))
(nreverse cands))))
(defun org-roam-link--get-file-from-title (title &optional no-interactive)
"Return the file path corresponding to TITLE.
When NO-INTERACTIVE, return nil if there are multiple options."
(let ((files (mapcar #'car (org-roam-db-query [:select [titles:file] :from titles
:where (= titles:title $v1)]
(vector title)))))
(pcase files
('nil nil)
(`(,file) file)
(_
(unless no-interactive
(completing-read "Select file: " files))))))
(defun org-roam-link--get-id-from-headline (headline &optional file)
"Return (marker . id) correspondng to HEADLINE in FILE.
If FILE is nil, get ID from current buffer.
If there is no corresponding headline, return nil."
(save-excursion
(org-roam-with-file file 'keep
(let ((headlines (org-roam-link--get-headlines file 'with-markers)))
(when-let ((marker (cdr (assoc-string headline headlines))))
(goto-char marker)
(cons marker
(when org-roam-link-auto-replace
(org-id-get-create))))))))
;;; Path-related functions
(defun org-roam-link-get-path (path &optional type)
"Return the PATH of the link to use.
If TYPE is non-nil, create a link of TYPE. Otherwise, respect
`org-link-file-path-type'."
(pcase (or type org-roam-link-file-path-type)
('absolute
(abbreviate-file-name (expand-file-name path)))
('noabbrev
(expand-file-name path))
('relative
(file-relative-name path))))
(defun org-roam-link--split-path (path)
"Splits PATH into title and headline.
Return a list of the form (type title has-headline-p headline star-idx).
type is one of `title', `headline', `title+headline'.
title is the title component of the path.
headline is the headline component of the path.
star-idx is the index of the asterisk, if any."
(save-match-data
(let* ((star-index (string-match-p "\\*" path))
(title (substring-no-properties path 0 star-index))
(headline (if star-index
(substring-no-properties path (+ 1 star-index))
""))
(type (cond ((not star-index)
'title)
((= 0 star-index)
'headline)
(t 'title+headline))))
(list type title headline star-index))))
(defun org-roam-link--get-location ()
"Return the location of the Org-roam fuzzy link at point.
The location is returned as a list containing (link-type loc desc marker).
nil is returned if there is no matching location.
link-type is either \"file\" or \"id\".
loc is the target location: e.g. a file path, or an id.
marker is a marker to the headline, if applicable.
desc is either the the description of the link under point, or
the target of LINK (title or heading content)."
(let ((context (org-element-context))
mkr link-type desc loc)
(pcase (org-element-lineage context '(link) t)
(`nil (error "Not at an Org link"))
(link
(if (not (string-equal "roam" (org-element-property :type link)))
(error "Not at Org-roam link")
(setq desc (and (org-element-property :contents-begin link)
(org-element-property :contents-end link)
(buffer-substring-no-properties
(org-element-property :contents-begin link)
(org-element-property :contents-end link))))
(pcase-let ((`(,type ,title ,headline _) (org-roam-link--split-path
(org-element-property :path link))))
(pcase type
('title+headline
(let ((file (org-roam-link--get-file-from-title title)))
(if (not file)
(org-roam-message "Cannot find matching file")
(setq mkr (org-roam-link--get-id-from-headline headline file))
(pcase mkr
(`(,marker . ,target-id)
(progn
(setq mkr marker
loc target-id
desc (or desc headline)
link-type "id")))
(_ (org-roam-message "Cannot find matching id"))))))
('title
(setq loc (org-roam-link--get-file-from-title title)
link-type "file"
desc (or desc title)))
('headline
(setq mkr (org-roam-link--get-id-from-headline headline))
(pcase mkr
(`(,marker . ,target-id)
(setq mkr marker
loc target-id
link-type "id"
desc (or desc headline)))
(_ (org-roam-message "Cannot find matching headline")))))))))
(list link-type loc desc mkr)))
;;; Conversion Functions
(defun org-roam-link--replace-link (link-type loc &optional desc)
"Replace link at point with a vanilla Org link.
LINK-TYPE is the Org link type, typically \"file\" or \"id\".
LOC is path for the Org link.
DESC is the link description."
(save-excursion
(save-match-data
(unless (org-in-regexp org-link-bracket-re 1)
(user-error "No link at point"))
(replace-match "")
(insert (org-roam-format-link loc desc link-type)))))
(defun org-roam-link-replace-all ()
"Replace all roam links in the current buffer."
(interactive)
(save-excursion
(goto-char (point-min))
(while (re-search-forward org-link-bracket-re nil t)
(condition-case nil
(pcase-let ((`(,link-type ,loc ,desc _) (org-roam-link--get-location)))
(when (and link-type loc)
(org-roam-link--replace-link link-type loc desc)))
(error nil)))))
(defun org-roam-link--replace-link-on-save ()
"Hook to replace all roam links on save."
(when org-roam-link-auto-replace
(org-roam-link-replace-all)))
;;; Completion
(defun org-roam-link-complete-at-point ()
"Do appropriate completion for the link at point."
(let ((end (point))
(start (point))
collection link-type headline-only-p)
(when (org-in-regexp org-link-bracket-re 1)
(setq start (match-beginning 1)
end (match-end 1))
(let ((context (org-element-context)))
(pcase (org-element-lineage context '(link) t)
(`nil nil)
(link
(setq link-type (org-element-property :type link))
(when (member link-type '("roam" "fuzzy"))
(when (string= link-type "roam") (setq start (+ start (length "roam:"))))
(pcase-let ((`(,type ,title _ ,star-idx)
(org-roam-link--split-path (org-element-property :path link))))
(pcase type
('title+headline
(when-let ((file (org-roam-link--get-file-from-title title t)))
(setq collection (apply-partially #'org-roam-link--get-headlines file))
(setq start (+ start star-idx 1))))
('title
(setq collection #'org-roam-link--get-titles))
('headline
(setq collection #'org-roam-link--get-headlines)
(setq start (+ start star-idx 1))
(setq headline-only-p t)))))))))
(when collection
(let ((prefix (buffer-substring-no-properties start end)))
(list start end
(if (functionp collection)
(completion-table-case-fold
(completion-table-dynamic
(lambda (_)
(cl-remove-if (apply-partially #'string= prefix)
(funcall collection))))
(not org-roam-completion-ignore-case))
collection)
:exit-function
(lambda (str &rest _)
(delete-char (- 0 (length str)
(if headline-only-p 1 0)))
(insert (concat (unless (string= link-type "roam") "roam:")
(when headline-only-p "*")
(org-link-escape str)))))))))
(provide 'org-roam-link)
;;; org-roam-link.el ends here

88
org-roam-macs.el
View File

@ -5,8 +5,8 @@
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 1.2.3
;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
;; 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,30 +27,20 @@
;;; Commentary:
;;
;; This library implements macros and utility functions used throughout
;; org-roam.
;;
;; This library implements macros used throughout org-roam.
;;
;;; Code:
;;;; Library Requires
(require 'dash)
(require 's)
(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)
;;;; 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)))
(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.
@ -58,6 +48,7 @@ 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
@ -66,6 +57,11 @@ Kills the buffer if KEEP-BUF-P is nil, and FILE is not yet visited."
(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)))
@ -74,57 +70,21 @@ Kills the buffer if KEEP-BUF-P is nil, and FILE is not yet visited."
(kill-buffer (find-buffer-visiting ,file))))
res))
(defmacro org-roam--with-temp-buffer (file &rest body)
(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 `org-roam-temp-file-name' to file and insert its contents."
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)
(org-mode-hook nil)
(org-inhibit-startup t))
(org-mode)
(let ((org-roam-directory ,current-org-roam-directory))
(delay-mode-hooks (org-mode))
(when ,file
(insert-file-contents ,file)
(setq-local org-roam-file-name ,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))))
(defun org-roam-string-quote (str)
"Quote STR."
(->> str
(s-replace "\\" "\\\\")
(s-replace "\"" "\\\"")))
;;; Shielding regions
(defun org-roam-shield-region (beg end)
"Shield REGION against modifications.
REGION must be a cons-cell containing the marker to the region
beginning and maximum values."
(when (and beg end)
(add-text-properties beg end
'(font-lock-face org-roam-link-shielded
read-only t)
(marker-buffer beg))
(cons beg end)))
(defun org-roam-unshield-region (beg end)
"Unshield the shielded REGION."
(when (and beg end)
(let ((inhibit-read-only t))
(remove-text-properties beg end
'(font-lock-face org-roam-link-shielded
read-only t)
(marker-buffer beg)))
(cons beg end)))
(provide 'org-roam-macs)
;;; org-roam-macs.el ends here

192
org-roam-migrate.el Normal file
View File

@ -0,0 +1,192 @@
;;; org-roam-migrate.el --- Migration utilities from v1 to v2 -*- 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.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:
;;
;; 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:
;;;; Dependencies
;;;;
;;; v1 breaking warning
(require 'org-roam-db)
(defvar org-roam-v2-ack nil)
(unless org-roam-v2-ack
(lwarn 'org-roam :error "
------------------------------------
WARNING: You're now on Org-roam v2!
------------------------------------
You may have arrived here from a package upgrade. Please read the
wiki entry at
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 v1, but you can upgrade
them to the v2 format via a simple command. To migrate your
notes, run:
M-x org-roam-migrate-wizard
If you wish to stay on v1, v1 is unfortunately not distributed on
MELPA. See org-roam/org-roam-v1 on GitHub on how to install v1.
If you've gone through the migration steps (if necessary), and
know what you're doing set `org-roam-v2-ack' to `t' to disable
this warning. You can do so by adding:
(setq org-roam-v2-ack t)
To your init file.
"))
;;;###autoload
(defun org-roam-migrate-wizard ()
"Migrate all notes from to be compatible with Org-roam v2.
1. Convert all notes from v1 format to v2.
2. Rebuild the cache.
3. Replace all file links with ID links."
(interactive)
(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)))))
(message "Backing up files to %s" backup-dir)
(copy-directory org-roam-directory backup-dir))
;; 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)
;;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)))))
(defun org-roam-migrate-v1-to-v2 ()
"Convert the current buffer to v2 format."
;; Create file level ID
(org-with-point-at 1
(org-id-get-create))
;; Replace roam_key into properties drawer roam_ref
(when-let* ((refs (mapcan #'split-string-and-unquote
(cdar (org-collect-keywords '("roam_key"))))))
(let ((case-fold-search t))
(org-with-point-at 1
(dolist (ref refs)
(org-roam-ref-add ref))
(while (re-search-forward "^#\\+roam_key:" (point-max) t)
(beginning-of-line)
(kill-line 1)))))
;; Replace roam_alias into properties drawer roam_aliases
(when-let* ((aliases (mapcan #'split-string-and-unquote
(cdar (org-collect-keywords '("roam_alias"))))))
(let ((case-fold-search t))
(org-with-point-at 1
(dolist (alias aliases)
(org-roam-alias-add alias))
(while (re-search-forward "^#\\+roam_alias:" (point-max) t)
(beginning-of-line)
(kill-line 1)))))
;; Replace #+roam_tags into #+filetags
(org-with-point-at 1
(let* ((roam-tags (org-roam-migrate-get-prop-list "ROAM_TAGS"))
(file-tags (org-roam-migrate-get-prop-list "FILETAGS"))
(tags (append roam-tags file-tags))
(tags (seq-map (lambda (tag)
(replace-regexp-in-string
"[^[:alnum:]_@#%]"
"_"
tag)) tags))
(tags (seq-uniq tags)))
(when 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)
(beginning-of-line)
(kill-line 1)))))
(save-buffer))
(defun org-roam-migrate-get-prop-list (keyword)
"Return prop list for KEYWORD."
(let ((re (format "^#\\+%s:[ \t]*\\([^\n]+\\)" (upcase keyword)))
lst)
(goto-char (point-min))
(while (re-search-forward re 2048 t)
(setq lst (append lst (split-string-and-unquote
(buffer-substring-no-properties
(match-beginning 1) (match-end 1))))))
lst))
(defun org-roam-migrate-prop-set (name value)
"Set a file property called NAME to VALUE in buffer file.
If the property is already set, replace its value."
(setq name (downcase name))
(org-with-point-at 1
(let ((case-fold-search t))
(if (re-search-forward (concat "^#\\+" name ":\\(.*\\)")
(point-max) t)
(replace-match (concat "#+" name ": " value) 'fixedcase)
(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 "#+" name ": " value "\n")))))
(defun org-roam-migrate-replace-file-links-with-id ()
"Replace all file: links with ID links in current buffer."
(org-with-point-at 1
(while (re-search-forward org-link-bracket-re nil t)
(let* ((mdata (match-data))
(path (match-string 1))
(desc (match-string 2)))
(when (string-prefix-p "file:" path)
(setq path (expand-file-name (substring path 5)))
(when-let ((node-id (caar (org-roam-db-query [:select [id] :from nodes
:where (= file $s1)
:and (= level 0)] path))))
(set-match-data mdata)
(replace-match (org-link-make-string (concat "id:" node-id) desc))))))))
(provide 'org-roam-migrate)
;;; org-roam-migrate.el ends here

468
org-roam-mode.el Normal file
View File

@ -0,0 +1,468 @@
;;; 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.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 the abstract major-mode `org-roam-mode', from which
;; almost all other Org-roam major-modes derive.
;;
;;; Code:
(require 'magit-section)
(require 'org-roam-utils)
(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
`((((class color) (background light))
,@(and (>= emacs-major-version 27) '(:extend t))
:foreground "DarkGoldenrod4"
:weight bold)
(((class color) (background dark))
,@(and (>= emacs-major-version 27) '(:extend t))
:foreground "LightGoldenrod2"
:weight bold))
"Face for the `header-line' in some Org-roam modes."
:group 'org-roam-faces)
(defface org-roam-title
'((t :weight bold))
"Face for Org-roam titles."
:group 'org-roam-faces)
(defface org-roam-olp
'((((class color) (background light)) :foreground "grey60")
(((class color) (background dark)) :foreground "grey40"))
"Face for the OLP of the node."
:group 'org-roam-faces)
(defface org-roam-preview-heading
`((((class color) (background light))
,@(and (>= emacs-major-version 27) '(:extend t))
:background "grey80"
:foreground "grey30")
(((class color) (background dark))
,@(and (>= emacs-major-version 27) '(:extend t))
:background "grey25"
:foreground "grey70"))
"Face for preview headings."
:group 'org-roam-faces)
(defface org-roam-preview-heading-highlight
`((((class color) (background light))
,@(and (>= emacs-major-version 27) '(:extend t))
:background "grey75"
:foreground "grey30")
(((class color) (background dark))
,@(and (>= emacs-major-version 27) '(:extend t))
:background "grey35"
:foreground "grey70"))
"Face for current preview headings."
:group 'org-roam-faces)
(defface org-roam-preview-heading-selection
`((((class color) (background light))
,@(and (>= emacs-major-version 27) '(:extend t))
:inherit org-roam-preview-heading-highlight
:foreground "salmon4")
(((class color) (background dark))
,@(and (>= emacs-major-version 27) '(:extend t))
:inherit org-roam-preview-heading-highlight
:foreground "LightSalmon3"))
"Face for selected preview headings."
:group 'org-roam-faces)
(defface org-roam-preview-region
`((t :inherit bold
,@(and (>= emacs-major-version 27)
(list :extend (ignore-errors (face-attribute 'region :extend))))))
"Face used by `org-roam-highlight-preview-region-using-face'.
This face is overlaid over text that uses other hunk faces,
and those normally set the foreground and background colors.
The `:foreground' and especially the `:background' properties
should be avoided here. Setting the latter would cause the
loss of information. Good properties to set here are `:weight'
and `:slant'."
:group 'org-roam-faces)
(defface org-roam-dim
'((((class color) (background light)) :foreground "grey60")
(((class color) (background dark)) :foreground "grey40"))
"Face for the dimmer part of the widgets."
:group 'org-roam-faces)
;;; 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-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 Org-roam's buffer."
:group 'org-roam
(face-remap-add-relative 'header-line 'org-roam-header-line))
;;; 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-render ()
"Render the current node at point."
(interactive)
(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 ()
"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")))
;;; Persistent buffer
(defvar org-roam-buffer "*org-roam*"
"The persistent Org-roam buffer name.")
(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 whether the current visibility state of the org-roam buffer.
Valid states are 'visible, 'exists and 'none."
(declare (side-effect-free t))
(inline-quote
(cond
((get-buffer-window org-roam-buffer) 'visible)
((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 `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--redisplay ()
"."
(add-hook 'post-command-hook #'org-roam-buffer--post-command-h nil t))
(add-hook 'org-roam-find-file-hook #'org-roam-buffer--redisplay)
;;; Sections
;;;; Backlinks
(cl-defstruct (org-roam-backlink (:constructor org-roam-backlink-create)
(:copier nil))
source-node target-node
point properties)
(cl-defmethod org-roam-populate ((backlink org-roam-backlink))
"Populate BACKLINK from database."
(setf (org-roam-backlink-source-node backlink)
(org-roam-populate (org-roam-backlink-source-node backlink))
(org-roam-backlink-target-node backlink)
(org-roam-populate (org-roam-backlink-target-node backlink)))
backlink)
(defun org-roam-backlinks-get (node)
"Return the backlinks for NODE."
(let ((backlinks (org-roam-db-query
[:select [source dest pos properties]
:from links
:where (= dest $s1)
:and (= type "id")]
(org-roam-node-id node))))
(cl-loop for backlink in backlinks
collect (pcase-let ((`(,source-id ,dest-id ,pos ,properties) backlink))
(org-roam-populate
(org-roam-backlink-create
:source-node (org-roam-node-create :id source-id)
:target-node (org-roam-node-create :id dest-id)
:point pos
:properties properties))))))
(defun org-roam-backlinks-sort (a b)
"Default sorting function for backlinks A and B.
Sorts by title."
(string< (org-roam-node-title (org-roam-backlink-source-node a))
(org-roam-node-title (org-roam-backlink-source-node b))))
(defun org-roam-backlinks-section (node)
"The backlinks section for NODE."
(when-let ((backlinks (seq-sort #'org-roam-backlinks-sort (org-roam-backlinks-get node))))
(magit-insert-section (org-roam-backlinks)
(magit-insert-heading "Backlinks:")
(dolist (backlink backlinks)
(org-roam-node-insert-section
:source-node (org-roam-backlink-source-node backlink)
:point (org-roam-backlink-point backlink)
:properties (org-roam-backlink-properties backlink)))
(insert ?\n))))
;;;; Reflinks
(cl-defstruct (org-roam-reflink (:constructor org-roam-reflink-create)
(:copier nil))
source-node ref
point properties)
(cl-defmethod org-roam-populate ((reflink org-roam-reflink))
"Populate REFLINK from database."
(setf (org-roam-reflink-source-node reflink)
(org-roam-populate (org-roam-reflink-source-node reflink)))
reflink)
(defun org-roam-reflinks-get (node)
"Return the reflinks for NODE."
(let ((refs (org-roam-db-query [:select [ref] :from refs
:where (= node-id $s1)]
(org-roam-node-id node)))
links)
(pcase-dolist (`(,ref) refs)
(pcase-dolist (`(,source-id ,pos ,properties) (org-roam-db-query
[:select [source pos properties]
:from links
:where (= dest $s1)]
ref))
(push (org-roam-populate
(org-roam-reflink-create
:source-node (org-roam-node-create :id source-id)
:ref ref
:point pos
:properties properties)) links)))
links))
(defun org-roam-reflinks-sort (a b)
"Default sorting function for reflinks A and B.
Sorts by title."
(string< (org-roam-node-title (org-roam-reflink-source-node a))
(org-roam-node-title (org-roam-reflink-source-node b))))
(defun org-roam-reflinks-section (node)
"The reflinks section for NODE."
(when (org-roam-node-refs node)
(let* ((reflinks (seq-sort #'org-roam-reflinks-sort (org-roam-reflinks-get node))))
(magit-insert-section (org-roam-reflinks)
(magit-insert-heading "Reflinks:")
(dolist (reflink reflinks)
(org-roam-node-insert-section
:source-node (org-roam-reflink-source-node reflink)
:point (org-roam-reflink-point reflink)
:properties (org-roam-reflink-properties reflink)))
(insert ?\n)))))
;;;; 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-visit-thing] 'org-roam-file-visit)
map)
"Keymap for Org-roam grep result sections.")
(defclass org-roam-grep-section (magit-section)
((keymap :initform 'org-roam-grep-map)
(file :initform nil)
(row :initform nil)
(col :initform nil)))
(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)))
(with-current-buffer buf
(widen)
(goto-char (point-min))
(when row
(forward-line (1- row)))
(when col
(forward-char (1- col))))
(funcall (if other-window
#'switch-to-buffer-other-window
#'pop-to-buffer-same-window) buf)))
(defvar org-roam-unlinked-references-result-re
(rx (group (one-or-more anything))
":"
(group (one-or-more digit))
":"
(group (one-or-more digit))
":"
(group (zero-or-more anything)))
"Regex for the return result of a ripgrep query.")
(defun org-roam-unlinked-references-preview-line (file row)
"Return the preview line from FILE.
This is the ROW within FILE."
(with-temp-buffer
(insert-file-contents-literally file)
(forward-line (1- row))
(buffer-substring-no-properties
(save-excursion
(beginning-of-line)
(point))
(save-excursion
(end-of-line)
(point)))))
(defun org-roam-unlinked-references-section (node)
"The unlinked references section for NODE.
References from FILE are excluded."
(when (and (executable-find "rg")
(not (string-match "PCRE2 is not available"
(shell-command-to-string "rg --pcre2-version"))))
(let* ((titles (cons (org-roam-node-title node)
(org-roam-node-aliases node)))
(rg-command (concat "rg -o --vimgrep -P -i "
(mapconcat (lambda (glob) (concat "-g " glob))
(org-roam--list-files-search-globs org-roam-file-extensions)
" ")
(format " '\\[([^[]]++|(?R))*\\]%s' "
(mapconcat (lambda (title)
(format "|(\\b%s\\b)" (shell-quote-argument title)))
titles ""))
org-roam-directory))
(results (split-string (shell-command-to-string rg-command) "\n"))
f row col match)
(magit-insert-section (unlinked-references)
(magit-insert-heading "Unlinked References:")
(dolist (line results)
(save-match-data
(when (string-match org-roam-unlinked-references-result-re line)
(setq f (match-string 1 line)
row (string-to-number (match-string 2 line))
col (string-to-number (match-string 3 line))
match (match-string 4 line))
(when (and match
(not (f-equal-p (org-roam-node-file node) f))
(member (downcase match) (mapcar #'downcase titles)))
(magit-insert-section section (org-roam-grep-section)
(oset section file f)
(oset section row row)
(oset section col col)
(insert (propertize (format "%s:%s:%s"
(truncate-string-to-width (file-name-base f) 15 nil nil "...")
row col) 'font-lock-face 'org-roam-dim)
" "
(org-roam-fontify-like-in-org-mode
(org-roam-unlinked-references-preview-line f row))
"\n"))))))
(insert ?\n)))))
(provide 'org-roam-mode)
;;; org-roam-mode.el ends here

98
org-roam-overlay.el Normal file
View File

@ -0,0 +1,98 @@
;;; 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.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 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:
;;;; Dependencies
(defface org-roam-overlay
'((((class color) (background light))
:background "grey90" :box (:line-width -1 :color "black"))
(((class color) (background dark))
:background "grey10" :box (:line-width -1 :color "white")))
"Face for the Org-roam overlay."
:group 'org-roam-faces)
(defun org-roam-overlay--make (l r &rest props)
"Make an overlay from L to R with PROPS."
(let ((o (make-overlay l (or r l))))
(overlay-put o 'category 'org-roam)
(while props (overlay-put o (pop props) (pop props)))
o))
(defun org-roam-overlay-make-link-overlay (link)
"Create overlay for LINK."
(save-excursion
(save-match-data
(let* ((type (org-element-property :type link))
(id (org-element-property :path link))
(pos (org-element-property :end link))
(desc-p (org-element-property :contents-begin link))
node)
(when (and (string-equal type "id")
(setq node (org-roam-node-from-id id))
(not desc-p))
(org-roam-overlay--make
pos pos
'after-string (format "%s "
(propertize (org-roam-node-title node)
'face 'org-roam-overlay))))))))
(defun org-roam-overlay-enable ()
"Enable Org-roam overlays."
(org-roam-db-map-links
(list #'org-roam-overlay-make-link-overlay)))
(defun org-roam-overlay-disable ()
"Disable Org-roam overlays."
(remove-overlays nil nil 'category 'org-roam))
(defun org-roam-overlay-redisplay ()
"Redisplay Org-roam overlays."
(org-roam-overlay-disable)
(org-roam-overlay-enable))
(define-minor-mode org-roam-overlay-mode
"Overlays for Org-roam ID links.
Org-roam overlay mode is a minor mode. When enabled,
overlay displaying the node's title is displayed."
:lighter " org-roam-overlay"
(if org-roam-overlay-mode
(progn
(org-roam-overlay-enable)
(add-hook 'after-save-hook #'org-roam-overlay-redisplay nil t))
(org-roam-overlay-disable)
(remove-hook 'after-save-hook #'org-roam-overlay-redisplay t)))
(provide 'org-roam-overlay)
;;; org-roam-overlay.el ends here

74
org-roam-protocol.el
View File

@ -4,8 +4,8 @@
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; URL: https://github.com/org-roam/org-roam
;; Keywords: org-mode, roam, convenience
;; Version: 1.2.3
;; Package-Requires: ((emacs "26.1") (org "9.3"))
;; 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.
@ -31,12 +31,14 @@
;;
;; We define 2 protocols:
;;
;; 1. "roam-file": This protocol simply opens the file given by the FILE key
;; 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
@ -54,40 +56,34 @@ It opens or creates a note with the given ref.
encodeURIComponent(location.href) + \\='&title=\\=' + \\
encodeURIComponent(document.title) + \\='&body=\\=' + \\
encodeURIComponent(window.getSelection())"
(when-let* ((alist (org-roam--plist-to-alist info))
(decoded-alist (mapcar (lambda (k.v)
(let ((key (car k.v))
(val (cdr k.v)))
(cons key (org-link-decode val)))) alist)))
(unless (assoc 'ref decoded-alist)
(error "No ref key provided"))
(when-let ((title (cdr (assoc 'title decoded-alist))))
(push (cons 'slug (funcall org-roam-title-to-slug-function title)) decoded-alist))
(let-alist decoded-alist
(let* ((ref (org-protocol-sanitize-uri .ref))
(type (and (string-match org-link-plain-re ref)
(match-string 1 ref)))
(title (or .title ""))
(body (or .body ""))
(orglink
(org-link-make-string ref (or (org-string-nw-p title) ref))))
(when org-roam-protocol-store-links
(push (list ref title) org-stored-links))
(org-link-store-props :type type
:link ref
:annotation orglink
:initial body)))
(let* ((org-roam-capture-templates org-roam-capture-ref-templates)
(org-roam-capture--context 'ref)
(org-roam-capture--info decoded-alist)
(org-capture-link-is-already-stored t)
(template (cdr (assoc 'template decoded-alist))))
(raise-frame)
(org-roam-capture--capture nil template)
(org-roam-message "Item captured.")))
(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-file (info)
(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.
@ -95,15 +91,15 @@ It should contain the FILE key, pointing to the path of the file to open.
Example protocol string:
org-protocol://roam-file?file=/path/to/file.org"
(when-let ((file (plist-get info :file)))
org-protocol://roam-node?node=uuid"
(when-let ((node (plist-get info :node)))
(raise-frame)
(org-roam--find-file file))
(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-file" :protocol "roam-file" :function org-roam-protocol-open-file)
(push '("org-roam-node" :protocol "roam-node" :function org-roam-protocol-open-node)
org-protocol-protocol-alist)
(provide 'org-roam-protocol)

296
org-roam-utils.el Normal file
View File

@ -0,0 +1,296 @@
;;; org-roam-utils.el --- Utilities for Org-roam -*- 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 utility functions used throughout
;; Org-roam.
;;
;;
;;; Code:
;;;; Library Requires
(require 'dash)
(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))
(defun org-roam-quote-string (s)
"Quotes string S."
(->> s
(org-roam-replace "\\" "\\\\")
(org-roam-replace "\"" "\\\"")))
;;;; 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)))
(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))))))
(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))))
(defvar org-ref-buffer-hacked)
(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'."
;; NOTE: pretend that the temporary buffer created by `org-fontify-like-in-org-mode' to
;; fontify a `cite:' reference has been hacked by org-ref, whatever that means;
;;
;; `org-ref-cite-link-face-fn', which is used to supply a face for `cite:' links, calls
;; `hack-dir-local-variables' rationalizing that `bibtex-completion' would throw some warnings
;; otherwise. This doesn't seem to be the case and calling this function just before
;; `org-font-lock-ensure' (alias of `font-lock-ensure') actually instead of fixing the alleged
;; warnings messes the things so badly that `font-lock-ensure' crashes with error and doesn't let
;; org-roam to proceed further. I don't know what's happening there exactly but disabling this hackery
;; fixes the crashing. Fortunately, org-ref provides the `org-ref-buffer-hacked' switch, which we use
;; here to make it believe that the buffer was hacked.
;;
;; This is a workaround for `cite:' links and does not have any effect on other ref types.
;;
;; `org-ref-buffer-hacked' is a buffer-local variable, therefore we inline
;; `org-fontify-like-in-org-mode' here
(with-temp-buffer
(insert s)
(let ((org-ref-buffer-hacked t))
(org-mode)
(org-font-lock-ensure)
(buffer-string))))
(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).
This face is used on the region target by org-roam-insertion
during an `org-roam-capture'."
:group 'org-roam-faces)
(defun org-roam-shield-region (beg end)
"Shield region against modifications.
BEG and END are markers for the beginning and end regions.
REGION must be a cons-cell containing the marker to the region
beginning and maximum values."
(add-text-properties beg end
'(font-lock-face org-roam-shielded
read-only t)
(marker-buffer beg)))
(defun org-roam-unshield-region (beg end)
"Unshield the shielded REGION.
BEG and END are markers for the beginning and end regions."
(let ((inhibit-read-only t))
(remove-text-properties beg end
'(font-lock-face org-roam-shielded
read-only t)
(marker-buffer beg))))
;;; 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))))
(defvar org-roam--cached-display-format nil)
(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))))))
;;; 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.
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)
(beginning-of-line)
(delete-region (point) (line-end-position))
(delete-char 1)))))
(defun org-roam--kill-empty-buffer ()
"If the source buffer has been emptied, kill it.
If the buffer is associated with a file, delete the file.
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
;;;###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* ((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)))
;;;###autoload
(defun org-roam-diagnostics ()
"Collect and print info for `org-roam' issues."
(interactive)
(with-current-buffer (switch-to-buffer-other-window (get-buffer-create "*org-roam diagnostics*"))
(erase-buffer)
(insert (propertize "Copy info below this line into issue:\n" 'face '(:weight bold)))
(insert (format "- Emacs: %s\n" (emacs-version)))
(insert (format "- Framework: %s\n"
(condition-case _
(completing-read "I'm using the following Emacs framework:"
'("Doom" "Spacemacs" "N/A" "I don't know"))
(quit "N/A"))))
(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

2551
org-roam.el
View File

File diff suppressed because it is too large Load Diff

2
tests/roam-files/alias.org
View File

@ -1,2 +0,0 @@
#+roam_alias: "a1" "a 2"
#+title: t1

5
tests/roam-files/bar.org
View File

@ -1,3 +1,6 @@
:PROPERTIES:
:ID: 440795d0-70c1-4165-993d-aebd5eef7a24
:END:
#+title: Bar
This is file bar. Bar links to [[file:nested/bar.org][Nested Bar]].
[[id:884b2341-b7fe-434d-848c-5282c0727861][Foo]]

1
tests/roam-files/base.org
View File

@ -1 +0,0 @@
#+title: Base

1
tests/roam-files/cite_ref.org
View File

@ -1 +0,0 @@
#+roam_key: cite:mitsuha2007

10
tests/roam-files/foo.org
View File

@ -1,8 +1,4 @@
:PROPERTIES:
:ID: 884b2341-b7fe-434d-848c-5282c0727861
:END:
#+title: Foo
This is the foo file. It contains a link to [[file:bar.org][Bar]].
To make the tests more robust, here are some arbitrary links:
- [[https:google.com][Google]]
- [[mailto:foo@john.com][mail to foo]]

14
tests/roam-files/headlines/headline.org
View File

@ -1,14 +0,0 @@
#+TITLE: Headline
* Headline 1
:PROPERTIES:
:ID: e84d0630-efad-4017-9059-5ef917908823
:END:
* No headline here
Oops.
* Headline 2
:PROPERTIES:
:ID: 801b58eb-97e2-435f-a33e-ff59a2f0c213
:END:

2
tests/roam-files/multiple-refs.org
View File

@ -1,2 +0,0 @@
#+roam_key: https://www.orgroam.com/
#+roam_key: cite:orgroam2020

3
tests/roam-files/nested/bar.org
View File

@ -1,3 +0,0 @@
#+title: Nested Bar
This file is nested, 1 level deeper. It links to both [[file:../foo.org][Foo]] and [[file:foo.org][Nested Foo]].

1
tests/roam-files/nested/deeply/deeply_nested_file.org
View File

@ -1 +0,0 @@
#+title: Deeply Nested File

3
tests/roam-files/nested/foo.org
View File

@ -1,3 +0,0 @@
#+title: Nested Foo
This file has no links.

5
tests/roam-files/no-title.org
View File

@ -1,5 +0,0 @@
no title in this file :O
links to itself, with no title: [[file:no-title.org][no-title]]
* Headline title

3
tests/roam-files/tags/no_tag.org
View File

@ -1,3 +0,0 @@
#+title: Tagless File
This file has no tags, and should not yield any tags on extracting via ~#+roam_tags~.

5
tests/roam-files/tags/tag.org
View File

@ -1,5 +0,0 @@
#+roam_tags: "t1" "t2 with space" t3
#+roam_tags: "t4 second-line"
#+title: Tags
This file is used to test functionality for =(org-roam--extract-tags)=

2
tests/roam-files/titles/aliases.org
View File

@ -1,2 +0,0 @@
#+roam_alias: "roam" "alias"
#+roam_alias: "second" "line"

4
tests/roam-files/titles/combination.org
View File

@ -1,4 +0,0 @@
#+title: TITLE PROP
#+roam_alias: "roam" "alias"
* Headline

1
tests/roam-files/titles/headline.org
View File

@ -1 +0,0 @@
* Headline

1
tests/roam-files/titles/title.org
View File

@ -1 +0,0 @@
#+title: Title

3
tests/roam-files/unlinked.org
View File

@ -1,3 +0,0 @@
#+title: Unlinked
Nothing links here :(

1
tests/roam-files/web_ref.org
View File

@ -1 +0,0 @@
#+roam_key: https://google.com/

53
tests/test-org-roam-perf.el
View File

@ -1,53 +0,0 @@
;;; test-org-roam-perf.el --- Performance Tests for Org-roam -*- lexical-binding: t; -*-
;; Copyright (C) 2020 Jethro Kuan
;; Author: Jethro Kuan <jethrokuan95@gmail.com>
;; Package-Requires: ((buttercup))
;; 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 of the License, 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 this program. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;;; Code:
(require 'buttercup)
(require 'org-roam)
(defconst test-org-roam-perf-zip-url "https://github.com/org-roam/test-org-files/archive/master.zip"
"Path to zip for test org-roam files.")
(defun test-org-roam-perf--abs-path (file-path)
"Get absolute FILE-PATH from `org-roam-directory'."
(expand-file-name file-path org-roam-directory))
(defun test-org-roam-perf--init ()
"."
(let* ((temp-loc (expand-file-name (make-temp-name "test-org-files-") temporary-file-directory))
(zip-file-loc (concat temp-loc ".zip"))
(_ (url-copy-file test-org-roam-perf-zip-url zip-file-loc))
(_ (shell-command (format "mkdir -p %s && unzip -j -qq %s -d %s" temp-loc zip-file-loc temp-loc))))
(setq org-roam-directory temp-loc)))
(describe "Cache Build"
(it "cache build from scratch time to be acceptable"
(test-org-roam-perf--init)
(pcase (benchmark-run 1 (org-roam-db-build-cache t))
(`(,time ,gcs ,time-in-gc)
(message "Elapsed time: %fs (%fs in %d GCs)" time time-in-gc gcs)
(expect time :to-be-less-than 110))))
(it "builds quickly without change"
(pcase (benchmark-run 1 (org-roam-db-build-cache))
(`(,time ,gcs ,time-in-gc)
(message "Elapsed time: %fs (%fs in %d GCs)" time time-in-gc gcs)
(expect time :to-be-less-than 5)))))

344
tests/test-org-roam.el
View File

@ -23,341 +23,31 @@
(require 'buttercup)
(require 'org-roam)
(require 'dash)
(defun test-org-roam--abs-path (file-path)
"Get absolute FILE-PATH from `org-roam-directory'."
(expand-file-name file-path org-roam-directory))
(defun test-org-roam--find-file (path)
"PATH."
(let ((path (test-org-roam--abs-path path)))
(make-directory (file-name-directory path) t)
(find-file path)))
(defvar test-org-roam-directory (expand-file-name "tests/roam-files")
"Directory containing org-roam test org files.")
(defun test-org-roam--init ()
"."
(let ((original-dir test-org-roam-directory)
(new-dir (expand-file-name (make-temp-name "org-roam") temporary-file-directory)))
(copy-directory original-dir new-dir)
(setq org-roam-directory new-dir)
(org-roam-mode +1)
(sleep-for 2)))
(defun test-org-roam--teardown ()
(org-roam-mode -1)
(delete-file org-roam-db-location)
(org-roam-db--close))
(describe "Ref extraction"
(describe "org-roam-db-sync"
(before-all
(test-org-roam--init))
(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-setup))
(after-all
(test-org-roam--teardown))
(org-roam-teardown)
(delete-file org-roam-db-location))
(cl-flet
((test (fn file)
(let* ((fname (test-org-roam--abs-path file))
(buf (find-file-noselect fname)))
(with-current-buffer buf
;; Unlike tag extraction, it doesn't make sense to
;; pass a filename.
(funcall fn)))))
;; Enable "cite:" link parsing
(org-link-set-parameters "cite")
(it "extracts web keys"
(expect (test #'org-roam--extract-ref
"web_ref.org")
:to-equal
'("website" . "//google.com/")))
(it "extracts cite keys"
(expect (test #'org-roam--extract-ref
"cite_ref.org")
:to-equal
'("cite" . "mitsuha2007")))
(it "extracts all keys"
(expect (test #'org-roam--extract-refs
"multiple-refs.org")
:to-have-same-items-as
'(("cite" . "orgroam2020")
("website" . "//www.orgroam.com/"))))))
(describe "Title extraction"
:var (org-roam-title-sources)
(before-all
(test-org-roam--init))
(after-all
(test-org-roam--teardown))
(cl-flet
((test (fn file)
(let ((buf (find-file-noselect
(test-org-roam--abs-path file))))
(with-current-buffer buf
(funcall fn)))))
(it "extracts title from title property"
(expect (test #'org-roam--extract-titles-title
"titles/title.org")
:to-equal
'("Title"))
(expect (test #'org-roam--extract-titles-title
"titles/aliases.org")
:to-equal
nil)
(expect (test #'org-roam--extract-titles-title
"titles/headline.org")
:to-equal
nil)
(expect (test #'org-roam--extract-titles-title
"titles/combination.org")
:to-equal
'("TITLE PROP")))
(it "extracts alias"
(expect (test #'org-roam--extract-titles-alias
"titles/title.org")
:to-equal
nil)
(expect (test #'org-roam--extract-titles-alias
"titles/aliases.org")
:to-equal
'("roam" "alias" "second" "line"))
(expect (test #'org-roam--extract-titles-alias
"titles/headline.org")
:to-equal
nil)
(expect (test #'org-roam--extract-titles-alias
"titles/combination.org")
:to-equal
'("roam" "alias")))
(it "extracts headlines"
(expect (test #'org-roam--extract-titles-alias
"titles/title.org")
:to-equal
nil)
(expect (test #'org-roam--extract-titles-headline
"titles/aliases.org")
:to-equal
nil)
(expect (test #'org-roam--extract-titles-headline
"titles/headline.org")
:to-equal
'("Headline"))
(expect (test #'org-roam--extract-titles-headline
"titles/combination.org")
:to-equal
'("Headline")))
(describe "uses org-roam-title-sources correctly"
(it "'((title headline) alias)"
(expect (let ((org-roam-title-sources '((title headline) alias)))
(test #'org-roam--extract-titles
"titles/combination.org"))
:to-equal
'("TITLE PROP" "roam" "alias")))
(it "'((headline title) alias)"
(expect (let ((org-roam-title-sources '((headline title) alias)))
(test #'org-roam--extract-titles
"titles/combination.org"))
:to-equal
'("Headline" "roam" "alias")))
(it "'(headline alias title)"
(expect (let ((org-roam-title-sources '(headline alias title)))
(test #'org-roam--extract-titles
"titles/combination.org"))
:to-equal
'("Headline" "roam" "alias" "TITLE PROP"))))))
(describe "Tag extraction"
:var (org-roam-tag-sources)
(before-all
(test-org-roam--init))
(after-all
(test-org-roam--teardown))
(cl-flet
((test (fn file)
(let* ((fname (test-org-roam--abs-path file))
(buf (find-file-noselect fname)))
(with-current-buffer buf
(funcall fn fname)))))
(it "extracts from prop"
(expect (test #'org-roam--extract-tags-prop
"tags/tag.org")
:to-equal
'("t1" "t2 with space" "t3" "t4 second-line"))
(expect (test #'org-roam--extract-tags-prop
"tags/no_tag.org")
:to-equal
nil))
(it "extracts from all directories"
(expect (test #'org-roam--extract-tags-all-directories
"base.org")
:to-equal
nil)
(expect (test #'org-roam--extract-tags-all-directories
"tags/tag.org")
:to-equal
'("tags"))
(expect (test #'org-roam--extract-tags-all-directories
"nested/deeply/deeply_nested_file.org")
:to-equal
'("nested" "deeply")))
(it "extracts from last directory"
(expect (test #'org-roam--extract-tags-last-directory
"base.org")
:to-equal
nil)
(expect (test #'org-roam--extract-tags-last-directory
"tags/tag.org")
:to-equal
'("tags"))
(expect (test #'org-roam--extract-tags-last-directory
"nested/deeply/deeply_nested_file.org")
:to-equal
'("deeply")))
(it "extracts from first directory"
(expect (test #'org-roam--extract-tags-first-directory
"base.org")
:to-equal
nil)
(expect (test #'org-roam--extract-tags-first-directory
"tags/tag.org")
:to-equal
'("tags"))
(expect (test #'org-roam--extract-tags-first-directory
"nested/deeply/deeply_nested_file.org")
:to-equal
'("nested")))
(describe "uses org-roam-tag-sources correctly"
(it "'(prop)"
(expect (let ((org-roam-tag-sources '(prop)))
(test #'org-roam--extract-tags
"tags/tag.org"))
:to-equal
'("t1" "t2 with space" "t3" "t4 second-line")))
(it "'(prop all-directories)"
(expect (let ((org-roam-tag-sources '(prop all-directories)))
(test #'org-roam--extract-tags
"tags/tag.org"))
:to-equal
'("t1" "t2 with space" "t3" "t4 second-line" "tags"))))))
(describe "ID extraction"
(before-all
(test-org-roam--init))
(after-all
(test-org-roam--teardown))
(cl-flet
((test (fn file)
(let* ((fname (test-org-roam--abs-path file))
(buf (find-file-noselect fname)))
(with-current-buffer buf
(funcall fn fname)))))
(it "extracts ids"
(expect (test #'org-roam--extract-ids
"headlines/headline.org")
:to-have-same-items-as
`(["e84d0630-efad-4017-9059-5ef917908823" ,(test-org-roam--abs-path "headlines/headline.org") 1]
["801b58eb-97e2-435f-a33e-ff59a2f0c213" ,(test-org-roam--abs-path "headlines/headline.org") 1])))))
(describe "Test roam links"
(it ""
(expect (org-roam-link--split-path "")
(it "has the correct number of files"
(expect (caar (org-roam-db-query [:select (funcall count) :from files]))
:to-equal
'(title "" "" nil)))
(it "title"
(expect (org-roam-link--split-path "title")
2))
(it "has the correct number of nodes"
(expect (caar (org-roam-db-query [:select (funcall count) :from nodes]))
:to-equal
'(title "title" "" nil)))
(it "title*"
(expect (org-roam-link--split-path "title*")
2))
(it "has the correct number of links"
(expect (caar (org-roam-db-query [:select (funcall count) :from links]))
:to-equal
'(title+headline "title" "" 5)))
(it "title*headline"
(expect (org-roam-link--split-path "title*headline")
:to-equal
'(title+headline "title" "headline" 5)))
(it "*headline"
(expect (org-roam-link--split-path "*headline")
:to-equal
'(headline "" "headline" 0))))
;;; Tests
(xdescribe "org-roam-db-build-cache"
(before-each
(test-org-roam--init))
(after-each
(test-org-roam--teardown))
(it "initializes correctly"
;; Cache
(expect (caar (org-roam-db-query [:select (funcall count) :from files])) :to-be 8)
(expect (caar (org-roam-db-query [:select (funcall count) :from links])) :to-be 5)
(expect (caar (org-roam-db-query [:select (funcall count) :from titles])) :to-be 8)
(expect (caar (org-roam-db-query [:select (funcall count) :from titles
:where titles :is-null])) :to-be 1)
(expect (caar (org-roam-db-query [:select (funcall count) :from refs])) :to-be 1)
;; Links
(expect (caar (org-roam-db-query [:select (funcall count) :from links
:where (= source $s1)]
(test-org-roam--abs-path "foo.org"))) :to-be 1)
(expect (caar (org-roam-db-query [:select (funcall count) :from links
:where (= source $s1)]
(test-org-roam--abs-path "nested/bar.org"))) :to-be 2)
;; Links -- File-to
(expect (caar (org-roam-db-query [:select (funcall count) :from links
:where (= dest $s1)]
(test-org-roam--abs-path "nested/foo.org"))) :to-be 1)
(expect (caar (org-roam-db-query [:select (funcall count) :from links
:where (= dest $s1)]
(test-org-roam--abs-path "nested/bar.org"))) :to-be 1)
(expect (caar (org-roam-db-query [:select (funcall count) :from links
:where (= dest $s1)]
(test-org-roam--abs-path "unlinked.org"))) :to-be 0)
;; TODO Test titles
(expect (org-roam-db-query [:select * :from titles])
:to-have-same-items-as
(list (list (test-org-roam--abs-path "alias.org")
(list "t1" "a1" "a 2"))
(list (test-org-roam--abs-path "bar.org")
(list "Bar"))
(list (test-org-roam--abs-path "foo.org")
(list "Foo"))
(list (test-org-roam--abs-path "nested/bar.org")
(list "Nested Bar"))
(list (test-org-roam--abs-path "nested/foo.org")
(list "Nested Foo"))
(list (test-org-roam--abs-path "no-title.org")
(list "Headline title"))
(list (test-org-roam--abs-path "web_ref.org") nil)
(list (test-org-roam--abs-path "unlinked.org")
(list "Unlinked"))))
(expect (org-roam-db-query [:select * :from refs])
:to-have-same-items-as
(list (list "https://google.com/" (test-org-roam--abs-path "web_ref.org") "website")))
;; Expect rebuilds to be really quick (nothing changed)
(expect (org-roam-db-build-cache)
:to-equal
(list :files 0 :links 0 :tags 0 :titles 0 :refs 0 :deleted 0))))
1)))
(provide 'test-org-roam)