231 lines
8.6 KiB
Org Mode
231 lines
8.6 KiB
Org Mode
#+title: Org Journaling
|
||
#+author: Howard X. Abrams
|
||
#+date: 2020-09-24
|
||
#+tags: emacs org
|
||
|
||
A literate programming configuration file for extending the Journaling capabilities.
|
||
|
||
#+begin_src emacs-lisp :exports none
|
||
;;; org-journaling --- Configuring journals in org. -*- lexical-binding: t; -*-
|
||
;;
|
||
;; © 2020-2023 Howard X. Abrams
|
||
;; This work is licensed under a Creative Commons Attribution 4.0 International License.
|
||
;; See http://creativecommons.org/licenses/by/4.0/
|
||
;;
|
||
;; Author: Howard X. Abrams <http://gitlab.com/howardabrams>
|
||
;; Maintainer: Howard X. Abrams
|
||
;; Created: September 24, 2020
|
||
;;
|
||
;; This file is not part of GNU Emacs.
|
||
;;
|
||
;;; Commentary:
|
||
;;
|
||
;; *NB:* Do not edit this file. Instead, edit the original literate file at:
|
||
;; ~/src/hamacs/org-journaling.org
|
||
;; And tangle the file to recreate this one.
|
||
;;
|
||
;;; Code:
|
||
#+end_src
|
||
* Introduction
|
||
I used to use the [[https://github.com/bastibe/org-journal][org-journal]] project to create /daily/ journal entries, but what I like is one file per journal entry, and that project did more than I needed. I made my own.
|
||
|
||
My requirements are simple:
|
||
|
||
1. A directory of entries, =~/journal=. Each file is based on the date, e.g. =20241228= or =20130401=.
|
||
2. A minor mode to identify a journal entry as opposed to a regular org file.
|
||
|
||
Where do I store these?
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defvar org-journal-dir (expand-file-name "~/journal")
|
||
"Location of Journal entries, org files.")
|
||
#+END_SRC
|
||
|
||
And what identifies a Journal file?
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defvar org-journal-rx (rx (group (= 4 digit))
|
||
(optional "-")
|
||
(group (= 2 digit))
|
||
(optional "-")
|
||
(group (= 2 digit)))
|
||
"A regular expression that identifies journal file entries.")
|
||
#+END_SRC
|
||
And a function to create a new entry:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun org-journal-new-entry ()
|
||
"Opens today's journal entry file."
|
||
(interactive)
|
||
(find-file (expand-file-name (format-time-string "%Y%m%d")
|
||
org-journal-dir)))
|
||
#+END_SRC
|
||
|
||
And connect files that /look/ like a Journal entry with =org-mode=:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(add-to-list 'auto-mode-alist `(,org-journal-rx . org-mode))
|
||
#+END_SRC
|
||
|
||
And pull ‘er up:
|
||
#+BEGIN_SRC emacs-lisp
|
||
(ha-leader "f j" '("journal" . org-journal-new-entry))
|
||
#+END_SRC
|
||
|
||
This depends on the following [[file:~/.doom.d/snippets/org-journal-mode/__journal][snippet/template file]]:
|
||
|
||
#+begin_src snippet :tangle ~/src/hamacs/templates/journal
|
||
#+title: Journal Entry- `(ha-journal-file-datestamp)`
|
||
|
||
$0
|
||
#+end_src
|
||
|
||
And the code to connect that template to those files:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(ha-auto-insert-file (rx "journal/" (regexp org-journal-rx)) "journal")
|
||
#+END_SRC
|
||
|
||
Note that when I create a new journal entry, I want a title that should insert a date to match the file's name, not necessarily the current date (see below).
|
||
* Journal Filename to Date
|
||
Since the Journal's filename represents a date, I should be able to get the "date" associated with a file.
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun ha-journal-file-date (&optional datename)
|
||
"Return a Lisp date-timestamp from current filename.
|
||
If DATENAME is given, return that timestamp."
|
||
(unless datename
|
||
(setq datename (file-name-base (buffer-file-name))))
|
||
|
||
(when (string-match org-journal-rx datename)
|
||
(let ((day (string-to-number (match-string 3 datename)))
|
||
(month (string-to-number (match-string 2 datename)))
|
||
(year(string-to-number (match-string 1 datename))))
|
||
(encode-time 0 0 0 day month year))))
|
||
#+end_src
|
||
|
||
And some unit tests to validate this function:
|
||
|
||
#+begin_src emacs-lisp :tangle no
|
||
(ert-deftest ha-journal-file-date-test ()
|
||
(should (equal (ha-journal-file-date "20240817") '(26304 19056)))
|
||
(should (equal (ha-journal-file-date "2024-08-17") '(26304 19056))))
|
||
#+end_src
|
||
Using the "date" associated with a file, we can create our standard timestamp:
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun ha-journal-file-datestamp (&optional datename)
|
||
"Return date string of DATENAME if given.
|
||
If nil, use the buffer's filename's date."
|
||
(format-time-string "%e %b %Y (%A)" (ha-journal-file-date datename)))
|
||
#+end_src
|
||
* Journal Capture
|
||
Capturing a task (that when uncompleted, would then spillover to following days) could go to the daily journal entry. This requires a special function that opens today's journal, but specifies a non-nil prefix argument in order to inhibit inserting the heading, as =org-capture= will insert the heading.
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun org-journal-find-location ()
|
||
"Create or load a new journal buffer. Used for `org-capture'."
|
||
(org-journal-new-entry)
|
||
(goto-char (point-max)))
|
||
|
||
(defvar org-capture-templates (list))
|
||
|
||
(add-to-list 'org-capture-templates
|
||
'("j" "Journal Task/Entry" plain
|
||
(function org-journal-find-location)
|
||
"* %?\n\n %i\n\n From: %a"
|
||
:empty-lines 1 :jump-to-captured t :immediate-finish t))
|
||
#+end_src
|
||
* Next and Previous File
|
||
Sometimes it is obvious what is the /next file/ based on the one I'm currently reading. For instance, in my journal entries, the filename is a number that can be incremented. Same with presentation files...
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun split-string-with-number (str)
|
||
"Return list of three components of string, STR.
|
||
The first is the text prior to any numbers, The second is the
|
||
embedded number, and the third is the rest of the text in the
|
||
string."
|
||
(let* ((ms (string-match (rx (one-or-more digit)) str)))
|
||
(when ms
|
||
(list (substring str 0 ms)
|
||
(match-string 0 str)
|
||
(substring str
|
||
(+ ms
|
||
(length (match-string 0 str))))))))
|
||
#+end_src
|
||
|
||
Which means that the following defines this function:
|
||
|
||
#+begin_src emacs-lisp :tangle no
|
||
(ert-deftest split-string-default-separatorsg-with-number-test ()
|
||
(should (equal (split-string-with-number "abc42xyz") '("abc" "42" "xyz")))
|
||
(should (equal (split-string-with-number "42xyz") '("" "42" "xyz")))
|
||
(should (equal (split-string-with-number "abc42") '("abc" "42" "")))
|
||
(should (equal (split-string-with-number "20140424") '("" "20140424" "")))
|
||
(should (null (split-string-with-number "abcxyz"))))
|
||
#+end_src
|
||
|
||
Given this splitter function, we create a function that takes some sort of operator and return a new filename based on the conversion that happens:
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun find-file-number-change (f)
|
||
"Return a filename based on applying F to current buffer.
|
||
Where F would be something like `1+' or `1-'."
|
||
(let* ((filename (buffer-file-name))
|
||
(parts (split-string-with-number
|
||
(file-name-base filename)))
|
||
(new-name (number-to-string
|
||
(funcall f (string-to-number (nth 1 parts))))))
|
||
(concat (file-name-directory filename)
|
||
(nth 0 parts)
|
||
new-name
|
||
(nth 2 parts))))
|
||
#+end_src
|
||
|
||
And this allows us to create two simple functions that can load the "next" and "previous" files:
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun find-file-increment ()
|
||
"Load file that is _one more_ than the file in current buffer.
|
||
This requires that the current file contain a number that can be
|
||
incremented."
|
||
(interactive)
|
||
(find-file (find-file-number-change '1+)))
|
||
#+end_src
|
||
|
||
#+begin_src emacs-lisp
|
||
(defun find-file-decrement ()
|
||
"Load file that is _one less_ than the file in current buffer.
|
||
This requires that the current file contain a number that can be
|
||
decremented."
|
||
(interactive)
|
||
(find-file (find-file-number-change '1-)))
|
||
#+end_src
|
||
|
||
And we could bind those:
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(ha-leader "f +" '("next file" . find-file-increment)
|
||
"f -" '("previous file" . find-file-decrement))
|
||
#+END_SRC
|
||
|
||
* Technical Artifacts :noexport:
|
||
Let's =provide= a name so we can =require= this file.
|
||
|
||
#+begin_src emacs-lisp :exports none
|
||
(provide 'ha-org-journaling)
|
||
;;; ha-org-journaling.el ends here
|
||
#+end_src
|
||
|
||
Before you can build this on a new system, make sure that you put the cursor over any of these properties, and hit: ~C-c C-c~
|
||
|
||
#+description: A literate programming configuration file for extending the Journaling capabilities.
|
||
|
||
#+property: header-args:sh :tangle no
|
||
#+property: header-args:emacs-lisp :tangle yes
|
||
#+property: header-args :results none :eval no-export :comments no mkdirp yes
|
||
|
||
#+options: num:nil toc:t todo:nil tasks:nil tags:nil date:nil
|
||
#+options: skip:nil author:nil email:nil creator:nil timestamp:nil
|
||
#+infojs_opt: view:nil toc:t ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js
|