From 496cbadec1d3d6f4b7a66cd28cff248153b5ef5c Mon Sep 17 00:00:00 2001 From: TEC Date: Sun, 24 Jan 2021 03:45:02 +0800 Subject: [PATCH] Make many linters much happpier --- filters/_simple-headers.lua | 2 + org-pandoc-import-transient.el | 42 ++++++++++----- org-pandoc-import.el | 98 +++++++++++++++++++++------------- preprocessors/rmarkdown.el | 3 +- preprocessors/tsv.el | 3 +- 5 files changed, 94 insertions(+), 54 deletions(-) diff --git a/filters/_simple-headers.lua b/filters/_simple-headers.lua index 254466c..c779132 100644 --- a/filters/_simple-headers.lua +++ b/filters/_simple-headers.lua @@ -1,3 +1,5 @@ +-- SPDX-License-Identifier: GPL-3.0-or-later + local header_ids = {} local function collect_id (header) diff --git a/org-pandoc-import-transient.el b/org-pandoc-import-transient.el index 3d81539..dc7b323 100644 --- a/org-pandoc-import-transient.el +++ b/org-pandoc-import-transient.el @@ -1,13 +1,20 @@ -;;; org-pandoc-import-transient.el -*- lexical-binding: t; -*- +;;; org-pandoc-import-transient.el --- Convert other formats to Org on-the-fly -*- lexical-binding: t; -*- ;; This file is part of org-pandoc-import. ;; SPDX-License-Identifier: GPL-3.0-or-later +;;; Commentary: + +;; Utilise the work in `org-pandoc-import' to create a minor mode that enables +;; on-the-fly conversion to and from Org. + +;;; Code: + (require 'org-pandoc-import) (require 'org) (require 'ox-pandoc nil t) -(defcustom org-import-transient-async-export nil +(defcustom org-pandoc-import-transient-async-export nil "Whether or not to use Org's async export mode. This trades a short blocking period for a long non-blocking period." :type 'list @@ -19,12 +26,12 @@ This trades a short blocking period for a long non-blocking period." ("odt" . "odt") ("csv" . (lambda () (unless (org-at-table-p) - (user-error "Point is not inside a table.")) + (user-error "Point is not inside a table")) (org-table-export (concat (file-name-base (buffer-file-name)) ".csv") "orgtbl-to-csv"))) ("tsv" . (lambda () (unless (org-at-table-p) - (user-error "Point is not inside a table.")) + (user-error "Point is not inside a table")) (org-table-export (concat (file-name-base (buffer-file-name)) ".tsv") "orgtbl-to-tsv")))) (when (featurep 'ox-pandoc) @@ -69,7 +76,8 @@ the handler is called for the right file extensions." file-name-handler-alist))) (defun org-pandoc-import-transient--file-handler (operation &rest args) - "Expand file names through `org-pandoc-import-transient--file-handler' when mode is active." + "Expand file names through `org-pandoc-import-transient--file-handler' when +mode is active. Argument OPERATION is the file operation being performed." (let ((inhibit-file-name-handlers (cons 'org-pandoc-import-transient--file-handler (and (eq inhibit-file-name-operation operation) @@ -124,8 +132,8 @@ Returns information on the location and state of the converted file." (defun org-pandoc-import-transient--maybe-converted-org-file-handler (operation &rest args) "When an org file is saved, back-propogate the changes if appropriate. -This is done by exporting the org file to the target file type, after checking that the -curret file is indeed a transient conversion." +This is done by exporting the org file to the target file type, after checking +that the curret file is indeed a transient conversion." (let ((inhibit-file-name-handlers (cons 'org-pandoc-import-transient--maybe-converted-org-file-handler (and (eq inhibit-file-name-operation operation) @@ -160,21 +168,27 @@ curret file is indeed a transient conversion." (start-time (time-to-seconds (current-time)))) (if (functionp exporter) (funcall exporter) - (org-export-to-file (intern exporter) source-file org-import-transient-async-export)) + (org-export-to-file (intern exporter) source-file org-pandoc-import-transient-async-export)) (message "Updated %s in %2fs." source-file (- (time-to-seconds (current-time)) start-time))))) (t (apply operation args))) (apply operation args)))) (defun org-pandoc-import-transient--killed () - "When this buffer is closed, we assume that the source file is liable to be modified. + "When this buffer is closed, we assume that the source file may be modified. Thus, if we re-open the file with `org-pandoc-import-transient-mode' enabled, we want to re-create the associated org file." (plist-put (cdr (assoc (buffer-file-name) org-pandoc-import-transient--files)) :initialised nil)) -(defun org-pandoc-import-transient--cleanup () - "Deregister file handlers and remove all .opi-transient working dirs, to avoid cluttering. -Dirs to remove are found from `org-pandoc-import-transient--files'." - (org-pandoc-import-transient--deregister-file-handlers) +(defun org-pandoc-import-transient-cleanup (&optional keep-file-handlers) + "Remove all .opi-transient working dirs to avoid cluttering. +Dirs to remove are found from `org-pandoc-import-transient--files'. + +Unless KEEP-FILE-HANDLERS is set, the file handlers will be deregistered. +This KEEP-FILE-HANDLERS is observed when called interactively without +a prefix argument." + (interactive "p") + (unless (eq keep-file-handlers 1) + (org-pandoc-import-transient--deregister-file-handlers)) (dolist (transient-dir (delete-dups (mapcar #'file-name-directory @@ -185,7 +199,7 @@ Dirs to remove are found from `org-pandoc-import-transient--files'." (setq org-pandoc-import-transient--files nil)) (org-pandoc-import-transient--register-file-handlers) -(add-hook 'kill-emacs-hook #'org-pandoc-import-transient--cleanup) +(add-hook 'kill-emacs-hook #'org-pandoc-import-transient-cleanup) (provide 'org-pandoc-import-transient) diff --git a/org-pandoc-import.el b/org-pandoc-import.el index 3da305b..67c2465 100644 --- a/org-pandoc-import.el +++ b/org-pandoc-import.el @@ -2,7 +2,7 @@ ;; Copyright (C) 2020 TEC -;; Author: TEC +;; Author: TEC ;; Maintainer: TEC ;; Created: 16 Aug 2020 ;; Modified: August 29, 2020 @@ -32,9 +32,9 @@ ;;; Commentary: -;; Leverage Pandoc to convert non-org formats to org, and supplies a minor mode -;; to do on-the-fly conversion transparently and automatically, exporting -;; to the original format on save. +;; Leverage Pandoc to make convert non-org formats to org trivial. +;; Also supplies a minor mode to do on-the-fly conversion transparently +;; and automatically, exporting to the original format on save. ;;; Code: @@ -84,9 +84,10 @@ If FITERS/backend.lua exists, it will automatically be used when backend is regi (expand-file-name "preprocessors" org-pandoc-import-setup-folder) "A file to but pre-processors in. -When a new backend is defined,if PREPROCESSORS/backend.el exists it will be loaded, -and if org-pandoc-import-(backend)-preprocessor exists, it will be called -with the input file as the argument, and the result used as the new input file." +When a new backend is defined, if PREPROCESSORS/backend.el exists it will be +loaded, and if org-pandoc-import-backend-preprocessor exists (where backend a +placeholder for the actual backend name), it will be called with the input file +as the argument, and the result used as the new input file." :type 'string :group 'org-pandoc-import) @@ -94,8 +95,10 @@ with the input file as the argument, and the result used as the new input file." "List of arguments to apply to all backends. Accepts three types of atoms: - strings, which are passed as-is to `call-process' -- plist keywords, which have the : replaced with single dash if the word is one charachter, else two dashes -- functions, which are evaluated and have the result passed as one of the arguments" +- plist keywords, which have the : replaced with single dash if the word + is one charachter, else two dashes +- functions, which are evaluated and have the result passed as one + of the arguments" :type 'list :group 'org-pandoc-import) @@ -115,10 +118,13 @@ By default, all files starting with '_' in `org-pandoc-import-filters-folder' ar ;;;###autoload (defmacro org-pandoc-import-backend (name &optional recognised-extensions pandoc-type filters pandoc-args) - "Create an export backend named NAME which is applied by default on RECOGNISED-EXTENSIONS. -This calls pandoc, specifying the input format to be PANDOC-TYPE. PANDOC-ARGS is a list of args passed to -the pandoc command in the same manner as `org-pandoc-import-global-args'. -Filters can be either absolute paths to pandoc filters, or names of files within `org-pandoc-import-filters-folder'. + "Create an export backend named NAME. +The backend is applied by default on files which end in a RECOGNISED-EXTENSIONS. +This calls pandoc, specifying the input format to be PANDOC-TYPE. +PANDOC-ARGS is a list of args passed to the pandoc command in the same manner +as `org-pandoc-import-global-args'. +Filters can be either absolute paths to pandoc filters, or names of files +within `org-pandoc-import-filters-folder'. RECOGNISED-EXTENSIONS defaults to '(\"NAME\"), and PANDOC-TYPE to \"NAME\"." (let* ((s-name (symbol-name name)) @@ -171,19 +177,24 @@ Calls pandoc with arguments listed in `org-pandoc-import-%s-args', and filters ` (defun org-pandoc-import-convert (prompty out-file pandoc-type &optional in-file expected-extensions args filters syncronous-p preprocessor) "Call pandoc on an IN-FILE. -Determines the relevant paramaters to convert IN-FILE of type PANDOC-TYPE to either OUT-FILE, or a buffer (when OUT-FILE is nil). +Determines the relevant paramaters to convert IN-FILE of type PANDOC-TYPE to +either OUT-FILE, or a buffer (when OUT-FILE is nil). -If PROMPTY is non-nill, then the value of IN-FILE and (if applicable) OUT-FILE will be always prompted for. -A prompt for IN-FILE is also triggered when IN-FILE is nil, or its extension is not a member of EXPECTED-EXTENSIONS. -A prompt for OUT-FILE is triggered when OUT-FILE is t, or the name of a pre-existing file. -Pandoc is then called with arguments from the list ARGS - as described in `org-pandoc-import-global-args', -and filters named in the list FILTERS - which can be either absolute paths to pandoc filters, or names of files within `org-pandoc-import-filters-folder'. +If PROMPTY is non-nill, then the value of IN-FILE and (if applicable) OUT-FILE +will be always prompted for. A prompt for IN-FILE is also triggered when +IN-FILE is nil, or its extension is not a member of EXPECTED-EXTENSIONS. +A prompt for OUT-FILE is triggered when OUT-FILE is t, or the name of a +pre-existing file. Pandoc is then called with arguments from the list ARGS, +as described in `org-pandoc-import-global-args', and filters named in the list +FILTERS --- which can be either absolute paths to pandoc filters, or names of +files within `org-pandoc-import-filters-folder'. -If preprocessor is given, and a function, it is run with the value of IN-FILE. The value returned is used as the new IN-FILE." +If preprocessor is given, and a function, it is run with the value of IN-FILE. +The value returned is used as the new IN-FILE." (let* ((in-file (or in-file (if (and (not prompty) - (not (null (buffer-file-name))) + (buffer-file-name) (if expected-extensions (member (file-name-extension (buffer-file-name)) expected-extensions)) @@ -254,7 +265,10 @@ If preprocessor is given, and a function, it is run with the value of IN-FILE. T (set-process-sentinel process (org-pandoc-import-process-sentinel pandoc-buffer out-file (time-to-seconds (current-time))))))) (defun org-pandoc-import-process-sentinel (process-buffer &optional out-file start-time-seconds) - "Creats a lambda sentinel for a pandoc process." + "Creats a lambda sentinel for a pandoc process, outputing to PROCESS-BUFFER. +If OUT-FILE is given, kill the PROCESS-BUFFER and use the file in its place. +When START-TIME-SECONDS is given, a messege is generated indicating the total +time elapsed." (lambda (process _signal) (pcase (process-status process) ('exit (if out-file @@ -266,13 +280,13 @@ If preprocessor is given, and a function, it is run with the value of IN-FILE. T (message "Converted docunent in %3fs" (- (time-to-seconds (current-time)) start-time-seconds))) (org-mode)) ((or 'stop 'signal 'failed) - (user-error (format "The pandoc process to create %s has exited unexpectedly." out-file)) + (user-error "The pandoc process to create %s has exited unexpectedly." out-file) (switch-to-buffer process-buffer))))) (defun org-pandoc-import-generate-convert-arguments (in-file target-format &optional out-file arguments-list) "Format the provided arguments to be passed to pandoc. -Have pandoc convert IN-FILE of pandoc type TARGET-FORMAT to the org file OUT-FILE (if given), -with arguments given by ARGUMENTS-LIST." +Have pandoc convert IN-FILE of pandoc type TARGET-FORMAT to the org file +OUT-FILE (if given), with arguments given by ARGUMENTS-LIST." (let (arguments) (dolist (element (reverse (append arguments-list org-pandoc-import-global-args))) (push @@ -294,12 +308,15 @@ with arguments given by ARGUMENTS-LIST." ;;;###autoload (defun org-pandoc-import-as-org (prompty &optional in-file syncronous-p) - "Parse the provided file to org-mode, and open in a new buffer. -With PROMPTY (given by the universal argument), always prompt for the IN-FILE to act on. + "Parse the provided file to `org-mode', and open in a new buffer. +With PROMPTY (given by the universal argument), always prompt for the IN-FILE +to act on. -This only works so long as these is backend registered in `org-pandoc-import-backends' -associated with the extension of the selected file. See 'org-pandoc-import-{backend}-as-org' -for more information on a particular backend." +This only works so long as these is backend registered in +`org-pandoc-import-backends' associated with the extension of the selected file. +See org-pandoc-import-{backend}-as-org for information on a particular backend. + +When syncronous-p is set, the pandoc process is run in a blocking manner." (interactive "P") (if-let ((backend (org-pandoc-import-find-associated-backend (or in-file (buffer-file-name))))) (funcall (intern (format "org-pandoc-import-%s-as-org" (symbol-name backend))) @@ -308,13 +325,17 @@ for more information on a particular backend." ;;;###autoload (defun org-pandoc-import-to-org (prompty &optional in-file out-file syncronous-p) - "Parse the provided file to an org-mode file, and open. -With PROMPTY (given by the universal argument), always prompt for the IN-FILE to act on, -and the where to save the new Org file. + "Parse the provided file to an `org-mode' file, and open. +With PROMPTY (given by the universal argument), always prompt for the IN-FILE to +act on, and the where to save the new Org file. +The result is saved to OUT-FILE, which defaults to IN-FILE but with the .org +extension. -This only works so long as these is backend registered in `org-pandoc-import-backends' -associated with the extension of the selected file. See 'org-pandoc-import-{backend}-as-org' -for more information on a particular backend." +This only works so long as these is backend registered in +`org-pandoc-import-backends' associated with the extension of the selected file. +See org-pandoc-import-{backend}-as-org for information on a particular backend. + +When syncronous-p is set, the pandoc process is run in a blocking manner." (interactive "P") (if-let ((backend (org-pandoc-import-find-associated-backend (or in-file (buffer-file-name))))) (funcall (intern (format "org-pandoc-import-%s-to-org" (symbol-name backend))) @@ -323,8 +344,9 @@ for more information on a particular backend." (defun org-pandoc-import-find-associated-backend (file) - "Find the backend symbol from `org-pandoc-import-backends' associated with FILE's extension. -nil if no such association could be found." + "Find the backend symbol from associated with FILE's extension. +The backend is found from searching `org-pandoc-import-backends', and is nil +if no such match could be found." (when file (let ((ext (file-name-extension file)) the-backend) diff --git a/preprocessors/rmarkdown.el b/preprocessors/rmarkdown.el index d3c7e08..7c170f3 100644 --- a/preprocessors/rmarkdown.el +++ b/preprocessors/rmarkdown.el @@ -1,4 +1,5 @@ -;;; org-pandoc-import/preprocessors/rmarkdown.el -*- lexical-binding: t; -*- +;;; org-pandoc-import/preprocessors/rmarkdown.el --- Pre-process Rmarkdown files before importing -*- lexical-binding: t; -*- +;;; SPDX-License-Identifier: GPL-3.0-or-later (defun org-pandoc-import-rmarkdown-preprocessor (in-file) (let ((processed-file (make-temp-file "opif" nil ".Rmd"))) diff --git a/preprocessors/tsv.el b/preprocessors/tsv.el index 098e9da..d2f95cb 100644 --- a/preprocessors/tsv.el +++ b/preprocessors/tsv.el @@ -1,4 +1,5 @@ -;;; org-pandoc-import/preprocessors/tsv.el -*- lexical-binding: t; -*- +;;; org-pandoc-import/preprocessors/tsv.el --- Pre-process tsv files before importing -*- lexical-binding: t; -*- +;;; SPDX-License-Identifier: GPL-3.0-or-later (defun org-pandoc-import-tsv-preprocessor (in-file) (let ((processed-file (make-temp-file "opif" nil ".csv")))