org-drawer-list

Small utility library for dealing with lists in an org-mode drawer. This library provides the following functions:

• org-drawer-list - returns the content of the named drawer as a list;
• org-drawer-list-add - adds the value to the list under the named drawer;
• org-drawer-list-remove - removes the value from the list under the named drawer;
• org-drawer-list-contains - returns first element of the named drawer that is equal to a given element.
• org-drawer-list-block - returns the region of the named drawer; when asked creates a missing drawer.

Every function works also in the agenda buffer.

Please refer to each function’s documentation for more information.

Projects using this library

• orgability - reading list manager for Emacs with offline access support

User story

Imagine that you want to maintain a list of resources for each heading. One of the possible ways to organise it is to use custom drawers.

* fancy topic
:RESOURCES:
- resource one
- resource two
:END:

Easy and straight-forward. But manually updating this list is tedious, because manual work is tedious. And it doesn’t scale. Especially if you wish to write a program that leverages lists in custom drawers.

That’s where org-drawer-list comes to the rescue!

Getting the list of resources

(org-drawer-list "resources")
;; => ("resource one" "resource two")

(org-drawer-list "topics")
;; => nil

Adding resource

(org-drawer-list-add "resources" "resource three")
;; => "resource three"

* fancy topic
:RESOURCES:
- resource one
- resource two
- resource three
:END:

Removing resource

(org-drawer-list-remove "resources" "resource three")
;; => 1

* fancy topic
:RESOURCES:
- resource one
- resource two
:END:

Contains test

(org-drawer-list-contains "resources" "resource one")
;; => "resource one"

(org-drawer-list-contains "resources" "i don't exist")
;; => nil

(org-drawer-list-contains "resources" "one" #'string-suffix-p)
;; => "resource one"

Installation

Currently, this package is not available on MELPA, so you’ll have to manually install it.

use-package + quelpa

(use-package org-drawer-list
  :quelpa (org-drawer-list
           :fetcher github
           :repo "d12frosted/org-drawer-list"))

Testing

Ideally, you should use Cask for running tests. So first you need to install cask. If you are using emacs-plus, then you need to ignore dependencies during cask installation.

$ brew install cask --ignore-dependencies

One you have cask, you need to install all dependencies.

$ cask install

Now you can run tests.

$ cask exec ert-runner

Contributing

Everyone is welcome to contribute to org-drawer-list project. Feature requests, proposals, issue reports, documentation improvements, code patches - just to name few things that the project can gain from.

Please note that the main upstream of org-drawer-list is located on GitLab, and it’s advisable to send your contributions there. But they can be accepted also via email and GitHub.

This project has automated tests that are run on GitLab. If you are contributing outside of GitLab, please run the tests manually. For more information please refer to relevant section in readme file or contact me via email.

Happy hacking!