branch: master
commit 3b3625f94dcf9469260b4f56dac9dc3f9bcc43f8
Author: Ian D <du...@gnu.org>
Commit: Ian D <du...@gnu.org>
Cleaned up package header and added various docstrings
* org-edna.el (package header): Added Maintainer and URL
(Commentary): Added
(History): Added empty section
(org-edna-submit-bug-report): New interactive function.
---
org-edna.el | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 65 insertions(+), 3 deletions(-)
diff --git a/org-edna.el b/org-edna.el
index f980ba9..46046ab 100644
--- a/org-edna.el
+++ b/org-edna.el
@@ -3,9 +3,11 @@
;; Copyright (C) 2017 Ian Dunn
;; Author: Ian Dunn <du...@gnu.org>
+;; Maintainer: Ian Dunn <du...@gnu.org>
;; Keywords: convenience, text, org
-;; Version: 1.0
-;; Package-Requires: ((emacs "25.1") (seq "2.19") (org "8.0"))
+;; URL: https://savannah.nongnu.org/projects/org-edna-el/
+;; Package-Requires: ((emacs "25.1") (seq "2.19") (org "9.0.5"))
+;; Version: 1.0alpha1
;; This file is NOT part of GNU Emacs.
@@ -23,6 +25,14 @@
;;; Commentary:
+;; Edna provides an extensible means of specifying conditions which must be
+;; fulfilled before a task can be completed and actions to take once it is.
+
+;; Org Edna runs when either the BLOCKER or TRIGGER properties are set on a
+;; headline, and when it is changing from a TODO state to a DONE state.
+
+;;; History:
+
;;; Code:
(require 'org)
@@ -47,9 +57,15 @@ properties used during actions or conditions."
:type 'boolean)
(defmacro org-edna--syntax-error (msg form pos)
+ "Signal an Edna syntax error.
+
+MSG will be reported to the user and should describe the error.
+FORM is the form that generated the error.
+POS is the position in FORM at which the error occurred."
`(signal 'invalid-read-syntax (list :msg ,msg :form ,form :pos ,pos)))
(defun org-edna--print-syntax-error (error-plist)
+ "Prints the syntax error from ERROR-PLIST."
(let ((msg (plist-get error-plist :msg))
(form (plist-get error-plist :form))
(pos (plist-get error-plist :pos)))
@@ -71,7 +87,7 @@ Currently, the following are handled:
arg)))
(defun org-edna-parse-form (form &optional start)
- "Parse Edna form FORM."
+ "Parse Edna form FORM starting at position START."
(setq start (or start 0))
(pcase-let* ((`(,token . ,pos) (read-from-string form start))
(modifier nil)
@@ -98,6 +114,10 @@ Currently, the following are handled:
(list token args modifier pos)))
(defun org-edna--function-for-key (key)
+ "Determine the Edna function for KEY.
+
+KEY should be a symbol, the keyword for which to find the Edna
+function."
(cond
;; Just return nil if it's not a symbol; `org-edna-process-form' will handle
;; the rest
@@ -123,6 +143,7 @@ Currently, the following are handled:
(cons 'finder func-sym))))))
(defun org-edna--handle-condition (func mod args targets consideration)
+ "Handle a condition."
;; Check the condition at each target
(when-let ((blocks
(mapcar
@@ -134,6 +155,10 @@ Currently, the following are handled:
(org-edna-handle-consideration consideration blocks)))
(defun org-edna-process-form (form action-or-condition)
+ "Process FORM.
+
+ACTION-OR-CONDITION is a symbol, either 'action or 'condition,
+indicating whether FORM accepts actions or conditions."
(let ((targets)
(blocking-entry)
(consideration 'all)
@@ -196,6 +221,10 @@ Currently, the following are handled:
(defmacro org-edna-run (change-plist &rest body)
+ "Run a TODO state change.
+
+The state information is held in CHANGE-PLIST. If the TODO state
+is changing from a TODO state to a DONE state, run BODY."
(declare (indent 1))
`(let* ((pos (plist-get ,change-plist :position))
(type (plist-get ,change-plist :type))
@@ -221,11 +250,21 @@ Currently, the following are handled:
t)))
(defun org-edna-trigger-function (change-plist)
+ "Trigger function work-horse.
+
+See `org-edna-run' for CHANGE-PLIST explanation.
+
+This shouldn't be run from outside of `org-trigger-hook'."
(org-edna-run change-plist
(when-let ((form (org-entry-get pos "TRIGGER" org-edna-use-inheritance)))
(org-edna-process-form form 'action))))
(defun org-edna-blocker-function (change-plist)
+ "Blocker function work-horse.
+
+See `org-edna-run' for CHANGE-PLIST explanation.
+
+This shouldn't be run from outside of `org-blocker-hook'."
(org-edna-run change-plist
(if-let ((form (org-entry-get pos "BLOCKER" org-edna-use-inheritance)))
(org-edna-process-form form 'condition)
@@ -233,12 +272,19 @@ Currently, the following are handled:
;;;###autoload
(defun org-edna-load ()
+ "Setup the hooks necessary for Org Edna to run.
+
+This means adding to `org-trigger-hook' and `org-blocker-hook'."
(interactive)
(add-hook 'org-trigger-hook 'org-edna-trigger-function)
(add-hook 'org-blocker-hook 'org-edna-blocker-function))
;;;###autoload
(defun org-edna-unload ()
+ "Unload Org Edna.
+
+Remove Edna's workers from `org-trigger-hook' and
+`org-blocker-hook'."
(interactive)
(remove-hook 'org-trigger-hook 'org-edna-trigger-function)
(remove-hook 'org-blocker-hook 'org-edna-blocker-function))
@@ -617,6 +663,22 @@ IDS are all UUIDs as understood by `org-id-find'."
nil
first-block))))))
+
+
+(declare-function 'lm-report-bug "lisp-mnt" (topic))
+
+(defun org-edna-submit-bug-report (topic)
+ (interactive "sTopic: ")
+ (require 'lisp-mnt)
+ (let* ((src-file (locate-library "org-edna.el" t))
+ (src-buf-live (find-buffer-visiting src-file))
+ (src-buf (find-file-noselect src-file)))
+ (with-current-buffer src-buf
+ (lm-report-bug topic))
+ ;; Kill the buffer if it wasn't live
+ (unless src-buf-live
+ (kill-buffer src-buf))))
+
(provide 'org-edna)
;;; org-edna.el ends here
