wilderjds
/
poporg
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial commit, from files in the works.

Browse Source
master
François Pinard 13 years ago
parent 242a51d85e
commit 4dca6f94cc
5 changed files with 1369 additions and 4 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 4
      Makefile
  2. 4
      README.md
  3. 37
      README.org
  4. 318
      poporg.el
  5. 1010
      rebox.el

4
Makefile
Unescape View File

@ -0,0 +1,4 @@
# Internal goals
README.org: ~/fp/notes/pub/PopOrg.org
org-tool -g -p PopOrg.org >$@

4
README.md
Unescape View File

@ -1,4 +0,0 @@
PopOrg
======
Emacs programming tool for editing strings or comments in Org mode

37
README.org
Unescape View File

@ -0,0 +1,37 @@
#+TITLE: PopOrg — Editing program comments or strings with Org mode
#+OPTIONS: H:2
#+SETUPFILE: ~/fp/notes/setup/nodemacs.org
#+INCLUDE: ~/fp/notes/setup/jqindex.org
** Introduction
PopOrg is a small Emacs Lisp project, to help editing program string or comments using Org mode.
Literate programming with Org is often presented as mixing programs snippets within an Org document, with tools to extract pure programs out of the Org files. I would prefer it the other way around: mixing documentation snippets within program source code, with tools to extract pure Org documentation from the source files.
Emacs does not nicely handle multiple major modes in a single buffer. Many solutions are suggested, all yielding some level of happiness, but none are perfect. The PopOrg approach extracts the comment or the string, from a buffer using a major programming mode, into a separate buffer in full Org mode, but containing only that comment or string. Once the edit is completed, the modified comment or string is re-integrated in the buffer containing the program, replacing the original contents.
** Installation
To install PopOrg, move files =poporg.el= and =rebox.el= at a place where Emacs will find them. You might want to byte-compile the files if you want.
To use PopOrg, you need to pick some unused keybinding and add a few lines to your =~/.emacs= file. For one, I picked =C-c e o= and added these lines:
#+BEGIN_SRC sh
(autoload 'poporg-dwim "poporg" nil t)
(global-set-key "\C-ceo" 'poporg-dwim)
#+END_SRC
** Usage
While editing a buffer containing a program, you may edit a comment block or a string (often a doc-string) in Org mode by placing the cursor within or nearby that comment or string, and calling =poporg-dwim= using you selected keybinding. This pops another buffer in Org Mode (hence /PopOrg/ for the project name), containing the comment or string. Once your edition is done, right in the popped up editing buffer, call =poporg-dwim= again to complete the edition.
More precisely, if the cursor is within a comment block or a string, this is what gets edited. If the cursor is not within a comment block or a string, a comment or string following the cursor /on the same line/ gets selected instead. Otherwise, this is the comment or string which precedes the cursor which is selected for edition.
While the comment or string is being copied in the editing buffer and until the edition is completed, the original comment or string in the original buffer is greyed out and protected against accidental modification.
** History and caveats
PopOrg recycles a few ideas from two previous Emacs projects:
- my PO mode ([[http://git.savannah.gnu.org/cgit/gettext.git/tree/gettext-tools/misc/po-mode.el][source]] and [[http://www.gnu.org/software/gettext/manual/html_node/PO-Mode.html][documentation]]), for the idea of using separate buffers for edition. For PO files, the need is quite clear: =msgstr= strings use escaping which is easy to get wrong, so the idea of a separate buffer is a way to remove that concern from the user, PO mode unquotes before presenting the string to the user, and requotes it once the editing is completed. This was also solving the problem that =msgid= and =msgstr= fields, and the reminder of the PO file, could be using different character sets. I intend to recycle some ideas from PO mode for editing many comments and strings at once, instead of necessarily one after another.
- my Rebox tool ([[https://github.com/pinard/Pymacs/blob/master/contrib/rebox/rebox.el][source]] and [[https://github.com/pinard/Pymacs/blob/master/contrib/rebox/README][documentation]]), for finding the boundaries of block comments. Originally in Emacs Lisp, this tool has later rewritten in Python at the time I was developing Pymacs, with a few minor improvements while doing so. Le Wang, starting from my old Emacs Lisp, wrote an /much/ enhanced version ([[https://github.com/lewang/rebox2/blob/master/rebox2.el][source]] and [[http://youtube.googleapis.com/v/53YeTdVtDkU][video]]). For PopOrg, however, the needs are modest, so it includes the old Emacs Lisp version. See the very last section of the documentation for more historial context.
** Caveats
- I do not much like to depend on Rebox, however, which is a complex piece of code compared to the reminder of PopOrg. For comments, Rebox studies the file contents to guess comment delimiters and box styles, while for strings, PopOrg rather relies the syntax analysis previously made by the programming major mode, and expressed through faces. These approaches are too different, maybe both are wrong anyway. One advantage of using Rebox, however, is that one could still edit Org mode comments in complex boxing cases.
- Once the string and comment is back into the programming buffer, we loose Org mode highlighting and presentation details, which is unfortunate. Multiple editing modes in Emacs are not able to properly highlight sections of a file according to the intended mode for each section: there is a single mode for the whole buffer in fact. Org mode, on the other hand, has the virtue of properly highlighting the code snippets it contains, so surely, there is a way to do things properly, that might be understood and recycled, I'm not sure.
- PopOrg should ideally be accompanied by a set conventions and some tools for proper extraction of an Org file out of program sources.

318
poporg.el
Unescape View File

@ -0,0 +1,318 @@
;;; poporg.el --- Pop a region in a separate buffer for Org editing
;; Copyright 2013 Ubity inc.
;; Author: François Pinard
;; This is free software: you can redistribute it and/or modify it
;; under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This is distributed in the hope that it will be useful, but WITHOUT
;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
;; or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
;; License for more details.
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
;;; Commentary:
;; This pops a separate buffer for Org editing out of the contents of a comment,
;; then reinsert the modified comment in place once the edition is done.
;;; Todo:
;; - Prevent killing a main buffer with pending edits.
;; - Killing an edit buffer should imply =(poporg-edit-abort)=.
;; - While ending an edit, reveal all hidden text.
;; - Revise all FIXMEs in the code, to allow for many edits at once.
;;; Code:
;; Variables which are only meant for popped up editing buffers.
(defvar poporg-overlay nil
"Overlay, within the original buffer, corresponding to this edit.")
(defvar poporg-prefix nil
"Saved prefix, meant to be reapplied to all lines when the edit ends.")
;; FIXME (make-variable-buffer-local 'poporg-overlay)
;; FIXME (make-variable-buffer-local 'poporg-prefix)
;; In each buffer, list of dimming overlays for currently edited regions.
(defvar poporg-overlays nil
"List of overlays for all edits in the current buffer.
Right now, only one edit is allowed at a time, and this variable is global.")
;; FIXME (make-variable-buffer-local 'poporg-overlays)
(defface poporg-edited-face
'((((class color) (background light))
(:foreground "gray"))
(((class color) (background dark))
(:foreground "gray")))
"Face for a region while it is being edited.")
(defun poporg-current-line ()
"Return the contents of the line where the point is."
(buffer-substring-no-properties
(save-excursion (beginning-of-line) (point))
(save-excursion (end-of-line) (point))))
(defun poporg-dwim ()
(interactive)
"Single overall command for PopOrg (a single keybinding may do it all).
Edit either the active region, the comment or string containing
the cursor, after the cursor, else before the cursor. Within a
*PopOrg* edit buffer however, rather complete and exit the edit."
(cond ((string-equal (buffer-name) "*PopOrg*") (poporg-edit-exit))
;; FIXME (and (boundp 'poporg-overlay) poporg-overlay) (poporg-edit-exit))
((use-region-p) (poporg-edit-region (region-beginning) (region-end)))
((poporg-dwim-1 (point)))
((poporg-dwim-1
(let ((location (next-single-property-change (point) 'face)))
(or location (point-max)))))
((and (> (point) (point-min)) (poporg-dwim-1 (1- (point)))))
((poporg-dwim-1
(let ((location (previous-single-property-change (point) 'face)))
(if (and location (> location (point-min)))
(1- location)
(point-min)))))
(t (error "Nothing to edit!"))))
(defun poporg-dwim-1 (location)
"Possibly edit the comment or string surrounding LOCATION.
The edition occurs in a separate buffer. Return nil if nothing to edit."
(when location
(let ((face (get-text-property location 'face)))
(cond ((eq face 'font-lock-comment-delimiter-face)
(poporg-edit-comment location)
t)
((eq face 'font-lock-comment-face)
(poporg-edit-comment location)
t)
((eq face 'font-lock-doc-face)
;; As in Emacs Lisp doc strings.
(poporg-edit-string location)
t)
((eq face 'font-lock-string-face)
;; As in Python doc strings.
(poporg-edit-string location)
t)))))
(defun poporg-edit-comment (location)
"Discover the extent of current comment, then edit it in Org mode.
Point should be within a comment. The edition occurs in a separate buffer."
(require 'rebox)
(let (start end prefix)
(rebox-find-and-narrow)
(setq start (point-min)
end (point-max))
(widen)
(goto-char start)
(skip-chars-backward " ")
(setq start (point))
;; Set PREFIX.
(skip-chars-forward " ")
(skip-chars-forward comment-start)
(skip-chars-forward " ")
(setq prefix (buffer-substring-no-properties start (point))
prefix-regexp (regexp-quote prefix))
;; Edit our extended comment.
(poporg-edit-region start end prefix)))
(defun poporg-edit-comment-0 (location)
"Discover the extent of current comment, then edit it in Org mode.
Point should be within a comment. The edition occurs in a separate buffer."
;; FIXME: This is experimental.
(let (start end prefix)
(poporg-find-span '(font-lock-comment-delimiter-face
font-lock-comment-face))
(goto-char start)
(skip-chars-backward " ")
(setq start (point))
;; Set PREFIX.
(skip-chars-forward " ")
(skip-chars-forward comment-start)
(if (looking-at " ")
(forward-char))
(setq prefix (buffer-substring-no-properties start (point))
prefix-regexp (regexp-quote prefix))
;; Edit our extended comment.
(poporg-edit-region start end prefix)))
(defun poporg-edit-string (location)
"Discover the extent of current string, then edit it in Org mode.
Point should be within a string. The edition occurs in a separate buffer."
;; FIXME: This is experimental.
(let (start end prefix)
;; Set END.
(goto-char (or (next-single-property-change location 'face)
(point-max)))
(skip-chars-backward "\"'\\\n")
(when (looking-at "\n")
(forward-char))
(setq end (point))
;; Set START.
(goto-char (or (previous-single-property-change location 'face)
(point-min)))
(skip-chars-forward "\"'\\\\\n")
(setq start (point))
;; Set PREFIX.
(skip-chars-forward " ")
(setq prefix (buffer-substring-no-properties start (point)))
;; Edit our string.
(poporg-edit-region start end prefix)))
(defun poporg-edit-string-0 (location)
"Discover the extent of current string, then edit it in Org mode.
Point should be within a string. The edition occurs in a separate buffer."
;; FIXME: This is experimental.
(let (start end prefix)
(poporg-find-span '(font-lock-doc-face font-lock-string-face))
;; Set END.
(goto-char (or (next-single-property-change location 'face)
(point-max)))
(skip-chars-backward "\"'\\\n")
(when (looking-at "\n")
(forward-char))
(setq end (point))
;; Set START.
(goto-char (or (previous-single-property-change location 'face)
(point-min)))
(skip-chars-forward "\"'\\\\\n")
(setq start (point))
;; Set PREFIX.
(skip-chars-forward " ")
(setq prefix (buffer-substring-no-properties start (point)))
;; Edit our string.
(poporg-edit-region start end prefix)))
;; FIXME: Temporary debugging code.
(defvar debug-overlay (make-overlay 1 1))
(overlay-put debug-overlay 'face 'poporg-edited-face)
(defun poporg-edit-region-0 (start end &optional minimal-prefix)
(move-overlay debug-overlay start end (current-buffer)))
(defun poporg-edit-region (start end prefix)
"Setup an editing buffer in Org mode with region contents from START to END.
A prefix common to all buffer lines, and to PREFIX as well, gets removed."
(interactive "r")
(when poporg-overlays
(pop-to-buffer "*PopOrg*")
(error "PopOrg already in use"))
;; Losely reduced out of PO mode's po-edit-string.
(let ((start-marker (make-marker))
(end-marker (make-marker)))
(set-marker start-marker start)
(set-marker end-marker end)
(let ((buffer (current-buffer))
;; FIXME (edit-buffer (generate-new-buffer (concat "*" (buffer-name) "*")))
(edit-buffer "*PopOrg*")
(overlay (make-overlay start end))
(string (buffer-substring start end)))
;; Dim and protect the original text.
(overlay-put overlay 'face 'poporg-edited-face)
(overlay-put overlay 'intangible t)
(push overlay poporg-overlays)
;; Initialize a popup edit buffer.
(pop-to-buffer edit-buffer)
;; FIXME (make-local-variable 'poporg-overlay)
;; FIXME (make-local-variable 'poporg-prefix)
(setq poporg-overlay overlay)
(insert string)
;; Reduce prefix as needed.
(goto-char (point-min))
(while (not (eobp))
(setq prefix (or (fill-common-string-prefix
prefix (poporg-current-line))
""))
(forward-line 1))
(setq poporg-prefix prefix)
;; Remove common prefix.
(goto-char (point-min))
(while (not (eobp))
(delete-char (length prefix))
(forward-line 1))))
;; Switch to Org mode.
(goto-char (point-min))
(org-mode))
(defun poporg-edit-abort ()
"Exit the edit buffer, merely discarding its contents."
(interactive)
(let* ((edit-buffer (current-buffer))
(overlay poporg-overlay)
(buffer (overlay-buffer overlay)))
(if (null buffer)
(error "Corresponding buffer does not exist anymore")
(unless (one-window-p)
(delete-window))
(delete-overlay overlay)
(kill-buffer edit-buffer)
(setq poporg-overlays (delete overlay poporg-overlays))
)))
(defun poporg-edit-exit ()
"Exit the edit buffer, replacing the original region."
(interactive)
;; Reinsert the prefix.
(when poporg-prefix
(goto-char (point-min))
(while (not (eobp))
(insert poporg-prefix)
(forward-line 1)))
;; Move everything back in place.
(let* ((string (buffer-string))
(overlay poporg-overlay)
(start (overlay-start overlay))
(end (overlay-end overlay)))
(poporg-edit-abort)
(goto-char start)
(delete-region start end)
(insert string)))
(defun poporg-find-span (faces)
"Set START and END around point, extending over text having any of FACES.
The extension goes over single newlines and their surrounding whitespace.
START and END should be already bound within the caller."
;; FIXME: This is experimental.
;; Set START.
(save-excursion
(goto-char (or (previous-single-property-change (point) 'face)
(point-min)))
(setq start (point))
(skip-chars-backward " ")
(when (= (preceding-char) ?\n)
(forward-char -1)
(skip-chars-backward " ")
(while (and (not (bobp))
(memq (get-text-property (1- (point)) 'face) comment-faces))
(goto-char (or (previous-single-property-change (1- (point)) 'face)
(point-min)))
(setq start (point))
(skip-chars-backward " ")
(when (= (preceding-char) ?\n)
(forward-char -1)
(skip-chars-backward " ")))))
;; Set END.
(save-excursion
(goto-char (or (next-single-property-change (point) 'face)
(point-max)))
(setq end (point))
(skip-chars-forward " ")
(when (= (following-char) ?\n)
(forward-char)
(skip-chars-forward " ")
(while (memq (get-text-property (point) 'face) faces)
(goto-char (or (next-single-property-change (point) 'face)
(point-max)))
(setq end (point))
(skip-chars-forward " ")
(when (= (following-char) ?\n)
(forward-char)
(skip-chars-forward " "))))))
(provide 'poporg)
;;; poporg.el ends here

1010
rebox.el
View File

File diff suppressed because it is too large Load Diff
Write Preview
Loading…
Cancel
Save