From 6c050ce6f6216760c7355aaaf7fb02cf09faa8fa Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:16:13 -0500 Subject: [PATCH 01/13] Add hyphenation in docstring of org-babel-header-args:prolog --- ob-prolog.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ob-prolog.el b/ob-prolog.el index 354578f..c2ce0af 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -58,7 +58,7 @@ (defconst org-babel-header-args:prolog '((:goal . :any)) - "Prolog specific header arguments.") + "Prolog-specific header arguments.") (defvar org-babel-default-header-args:prolog From 69b227187623257e9794b8cd372c9aaab483d92e Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:17:10 -0500 Subject: [PATCH 02/13] Add docstring to org-babel-prolog--elisp-to-pl --- ob-prolog.el | 1 + 1 file changed, 1 insertion(+) diff --git a/ob-prolog.el b/ob-prolog.el index c2ce0af..7a257cf 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -65,6 +65,7 @@ `((:goal . nil))) (defun org-babel-prolog--elisp-to-pl (value) + "Convert the Emacs Lisp VALUE to equivalent Prolog." (cond ((stringp value) (format "'%s'" (replace-regexp-in-string From da9d8bece991303810aa39bf6245cb9a2051fefb Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:17:48 -0500 Subject: [PATCH 03/13] Add docstring to org-babel-prolog--variable-assignment --- ob-prolog.el | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ob-prolog.el b/ob-prolog.el index 7a257cf..c4c66b9 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -78,6 +78,12 @@ (t (prin1-to-string value)))) (defun org-babel-prolog--variable-assignment (pair) + "Return a string of a recorda/2 assertion of (cdr PAIR) under (car PAIR). + +The Emacs Lisp value of the car of PAIR is used as the Key argument to +recorda/2 without modification. The cdr of PAIR is converted to +equivalent Prolog before being provided as the Term argument to +recorda/2." (format "recorda('%s', %s)" (car pair) (org-babel-prolog--elisp-to-pl (cdr pair)))) From d5467fc88e2d995bbc076e7d84020b93793b10fb Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:18:05 -0500 Subject: [PATCH 04/13] Add docstring to org-babel-variable-assignments:prolog --- ob-prolog.el | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/ob-prolog.el b/ob-prolog.el index c4c66b9..4b80069 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -89,6 +89,11 @@ recorda/2." (org-babel-prolog--elisp-to-pl (cdr pair)))) (defun org-babel-variable-assignments:prolog (params) + "Return the babel variable assignments in PARAMS. + +PARAMS is a quasi-alist of header args, which may contain +multiple entries for the key `:var'. This function returns a +list of the cdr of all the `:var' entries." (let (vars) (dolist (param params vars) (when (eq (car param) :var) From 44dd096a4a19babe667fe2d7b801c635b40251d1 Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:19:04 -0500 Subject: [PATCH 05/13] Revise docstring of org-babel-prolog--parse-goal Reference the GOAL parameter correctly in the docstring. Remove the unnecessary and potentially confusing specification that GOAL is a Prolog goal. --- ob-prolog.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ob-prolog.el b/ob-prolog.el index 4b80069..7ea4037 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -103,7 +103,7 @@ list of the cdr of all the `:var' entries." (list (concat ":- " (mapconcat #'identity vars ", ") ".\n"))))) (defun org-babel-prolog--parse-goal (goal) - "Evaluate inline emacs-lisp in prolog goal parameter. + "Evaluate the inline Emacs Lisp in GOAL. Example: append(=(+ 2 3), =(quote a), B) From d1f147924a2006f209bdaa60e0406e3be420801f Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:21:13 -0500 Subject: [PATCH 06/13] Revise docstring of org-babel-execute:prolog Correctly reference the BODY and PARAMS parameters. Move the information about the function calling to a separate paragraph. --- ob-prolog.el | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ob-prolog.el b/ob-prolog.el index 7ea4037..84e3547 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -120,8 +120,9 @@ Example: (buffer-string)))) (defun org-babel-execute:prolog (body params) - "Execute a block of Prolog code with org-babel. This function is -called by `org-babel-execute-src-block'" + "Execute the Prolog in BODY according to the block's header PARAMS. + +This function is called by `org-babel-execute-src-block.'" (message "executing Prolog source code block") (let* ((result-params (cdr (assq :result-params params))) (session (cdr (assq :session params))) From 260566be8354bf44d717bea2dab34da57a87182b Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:24:02 -0500 Subject: [PATCH 07/13] Revise docstring of org-babel-prolog-evaluate-external-process Move the second sentence of the docstring to its own paragraph. Correct a typo in and modify the grammar of the second sentence. --- ob-prolog.el | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/ob-prolog.el b/ob-prolog.el index 84e3547..e81019a 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -155,9 +155,10 @@ This function is called by `org-babel-execute-src-block.'" (org-babel-prolog-initiate-session session))) (defun org-babel-prolog-evaluate-external-process (goal body) - "Evaluates the GOAL given the BODY in a external Prolog -process. If no GOAL is given the GOAL is replaced with HALT, -resulting in running just the body through the Prolog process." + "Evaluate the GOAL given the BODY in an external Prolog process. + +If no GOAL is given, the GOAL is replaced with HALT. This resulsts in +running just the body through the Prolog process." (let* ((tmp-file (org-babel-temp-file "prolog-")) (command (format "%s -q -l %s -t \"%s\"" org-babel-prolog-command From 9855c418db37154232f41920bfa08c100a6f2a99 Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:25:22 -0500 Subject: [PATCH 08/13] Revise docstring of org-babel-prolog-evaluate-session Move the second sentence to its own paragraph. Change the structure of the second sentence to clarify its meaning. --- ob-prolog.el | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ob-prolog.el b/ob-prolog.el index e81019a..c4727c4 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -170,8 +170,9 @@ running just the body through the Prolog process." (org-babel-eval command ""))) (defun org-babel-prolog-evaluate-session (session goal body) - "Evaluates the GOAL in the BODY of the prolog block in the -given SESSION. If there is no SESSION it creates it." + "In SESSION, evaluate GOAL given the BODY of the Prolog block. + +Create SESSION if it does not already exist." (let* ((session (org-babel-prolog-initiate-session session)) (body (split-string (org-babel-trim body) "\n"))) (org-babel-trim From 8b574d06702e226b1777f8ba87466309859e2ef8 Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:29:51 -0500 Subject: [PATCH 09/13] Add docstring to org-babel-prolog--answer-correction --- ob-prolog.el | 1 + 1 file changed, 1 insertion(+) diff --git a/ob-prolog.el b/ob-prolog.el index c4727c4..a138247 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -219,6 +219,7 @@ Create SESSION if it does not already exist." (buffer-string))))))) (defun org-babel-prolog--answer-correction (string) + "If STRING is Prolog's \"Correct to:\" prompt, send a refusal." (when (string-match-p "Correct to: \".*\"\\?" string) (insert "no") (comint-send-input nil t))) From 77b2d97aaaba27c77ab3a9d4e8d81655ccdf9a86 Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:30:19 -0500 Subject: [PATCH 10/13] Add docstring to org-babel-prolog--exit-debug --- ob-prolog.el | 1 + 1 file changed, 1 insertion(+) diff --git a/ob-prolog.el b/ob-prolog.el index a138247..9844ad2 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -225,6 +225,7 @@ Create SESSION if it does not already exist." (comint-send-input nil t))) (defun org-babel-prolog--exit-debug (string) + "If STRING indicates an exception, continue Prolog execution in no debug mode." (when (string-match-p "\\(.\\|\n\\)*Exception.* \\? $" string) (insert "no debug") (comint-send-input nil t))) From 50a61458649eb64fc3d1790e3957a65b6e9be31a Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:30:38 -0500 Subject: [PATCH 11/13] Revise docstring of org-babel-prolog-initiate-session Adhere to docstring convention by including entire first sentence on a single line. Use the second sentence (in its own paragraph) to describe the function's behavior if SESSION is not initialized prior to calling the function. --- ob-prolog.el | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ob-prolog.el b/ob-prolog.el index 9844ad2..f29fd8e 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -231,8 +231,9 @@ Create SESSION if it does not already exist." (comint-send-input nil t))) (defun org-babel-prolog-initiate-session (&optional session) - "If there is not a current inferior-process-buffer in SESSION -then create. Return the initialized session." + "Return SESSION with a current inferior-process-buffer. + +Initialize SESSION if it has not already been initialized." (unless (string= session "none") (let ((session (get-buffer-create (or session "*prolog*")))) (unless (comint-check-proc session) From 58811e524b9d9bc96f359c1254ad796dc76a449b Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:33:31 -0500 Subject: [PATCH 12/13] Use two spaces after sentences in the top matter commentary --- ob-prolog.el | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ob-prolog.el b/ob-prolog.el index f29fd8e..b300594 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -39,8 +39,8 @@ ;; install using the package manager. ;; ;; In addition to the normal header arguments ob-prolog also supports -;; the :goal argument. :goal is the goal that prolog will run when -;; executing the source block. Prolog needs a goal to know what it is +;; the :goal argument. :goal is the goal that prolog will run when +;; executing the source block. Prolog needs a goal to know what it is ;; going to execute. ;; From ddb19fc2ff0ca8486f81333251b3829c2d896e4c Mon Sep 17 00:00:00 2001 From: Joseph LaFreniere Date: Tue, 27 Mar 2018 19:40:07 -0500 Subject: [PATCH 13/13] Revise docstring of org-babel-load-session:prolog Correct the description of the function's actions. Indicate that the BODY and PARAMS parameters are unused. --- ob-prolog.el | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/ob-prolog.el b/ob-prolog.el index b300594..93decec 100644 --- a/ob-prolog.el +++ b/ob-prolog.el @@ -148,7 +148,9 @@ This function is called by `org-babel-execute-src-block.'" (cdr (assq :rownames params))))))) (defun org-babel-load-session:prolog (session body params) - "Load BODY into SESSION." + "Return initialized Prolog SESSION. + +BODY and PARAMS are both unused." (let* ((params (org-babel-process-params params)) (session (org-babel-prolog-initiate-session (cdr (assq :session session)))))