Re: narrow-to-here-document

[Masatake YAMATO <jet@gyve.org>]

Thank you for your comment.

> > I've written a new function, narrot-to-here-document.  This might be
> > useful to edit here document region in a script file.
> 
> > How to you think to add this feature to emacs?
> 
> > 1. hdoc.el --- Generic here document support
> > 2. sh-script.el and cperl-mode.el adapters
> 
> But are there any other modes with here-docs?

As far as I know ruby lang has "here document".
ruby-mode doesn't handle here document region now.

> I would do it like this:
> 
> a) defined a variable which keeps a function looking for a here-doc.
> 
> b) Merge your two adapters into one function (which makes a runtime
>    dispatch basing on the mode - and croaks if the mode is not known);
>    put the function into the variable.
> 
> c) delegate the other work to the mode writers - when a mode supports
>    an interaction with your function, it should make your variable
>    buffer-local, and will put its helper function into the variable.

a) and c) were done in the last patch I posted here.
To cover b), I'll move the adapters to hdoc.el itself.
Now only hdoc is needed. the patch for sh-script.el and cperl-mode.el
are not needed.

;;; hdoc.el --- Generic here document support

;; Copyright (C) 2003
;; 

;; Author: Masatake YAMATO<jet@gyve.org> 

;;; Commentary:

;;; Code:

(defvar here-document-region 'here-document-region-default
  "If non-nil, function for `narrow-to-here-document' to call.
This is used to find the beginning and end of the here document region in a
script file (see `narrow-to-here-document'). Major modes can define this
to handle the mode's needs.

The function should return a cons cell; its car is the position of 
beginning and cdr is that of end if the point is in a here document region. 
The function should return `nil' if the point is out of a here document region. ")

(defvar here-document-marker 'here-document-marker-default
  "If non-nil, function for `narrow-to-here-document' and `make-indirect-buffer-for-here-document' to call.
This is used to find the marker of the here document region in a
script file (see `make-indirect-buffer-for-here-document' and 
`narrow-to-here-document').  A string \"EOF\" is used widely as the marker 
but other string is also OK. Major modes can define this to handle the 
mode's needs.

The function should return a marker string if the point is in a here document 
region. Else it should return `nil'. ")

(define-key ctl-x-map "nh" 'narrow-to-here-document)
(define-key ctl-x-4-map "h" 'make-indirect-buffer-for-here-document)

(defun narrow-to-here-document (&optional change-major-mode)
  "Make text outside current here document region invisible.
Local variable `here-document-region' must be defined in the major 
mode to use this function.

If CHANGE-MAJOR-MODE is non-nil and local variable `here-document-marker' 
is defined in the major mode, major mode for the current buffer will be
switched; new major mode is selected according to the result of 
`here-document-marker'. For example if `here-document-marker' returns
\"EOF.c\", `c-mode' will be selected. Major mode selection is done
by `set-auto-mode'. In `set-auto-mode', `here-document-marker' is used
as the buffer's file name temporally.

To make text outside of the region visible, use \[widen]."
  (interactive "P")
  (let* ((marker (funcall here-document-marker))
	 (r      (funcall here-document-region))
	 (b      (car r))
	 (e      (cdr r)))
    (unless r
      (error "Cannot find here document region"))
    (narrow-to-region b e)
    (if (and change-major-mode marker)
	(let ((buffer-file-name marker))
	  (set-auto-mode)))))

(defun make-indirect-buffer-for-here-document (&optional change-major-mode)
  "Create and return an indirect buffer for current here document
region.  In the new indirect buffer, the text outside current here
document region is invisible(narrowed). Local variables `here-document-region' 
and `here-document-marker' must be defined in the major mode to use this function.

CHANGE-MAJOR-MODE is passed to `narrow-to-here-document'.
See also `narrow-to-here-document'.

The new indirect buffer name will be \"original-buffername<<here-document-marker\"."
  (interactive "P")
  (let  ((marker  (funcall here-document-marker))
	 (p       (point))
	 buf 
	 bufname)
    (unless marker
      (error "Cannot find here document marker"))
    (setq bufname (format "%s<<%s" (buffer-name) marker))
    (setq buf (make-indirect-buffer (current-buffer) bufname t))
    (pop-to-buffer buf)
    (goto-char p)
    (narrow-to-here-document change-major-mode)))

(defun here-document-region-default ()
  (cond 
   ((eq major-mode 'sh-mode)
    (sh-here-document-region))
   ((eq major-mode 'cperl-mode)
    (cperl-here-doc-region))
   (t
    (error "%s: `%s' is not supported in this major mode." 
	   mode-name
	   this-command))))

(defun here-document-marker-default ()
  (cond 
   ((eq major-mode 'sh-mode)
    (sh-here-document-marker))
   ((eq major-mode 'cperl-mode)
    (cperl-here-doc-delim))
   (t
    (error "%s: `%s' is not supported in this major mode." 
	   mode-name
	   this-command))))

;;
;; sh-mode
;;
(defun sh-here-document-region ()
  "Return here document region around the point.
Return nil if the point is not in a here document region."
  (let ((pos (point)))
    (if (eq 'sh-heredoc-face  (get-text-property pos 'face))
	(let ((b (previous-single-property-change pos 'face))
	      (e (next-single-property-change pos 'face)))
	  (setq b (if b (1+ b) (point-min)))
	  (setq e (if e (1- e) (point-max)))
	  (cons b e)))))

(defun sh-here-document-marker ()
  "Return the marker of here document region around the point.
Return nil if the point is not in a here document region. 
'EOF' is a typical marker. "
  (if (eq 'sh-heredoc-face  (get-text-property (point) 'face))
      (save-excursion
	(save-match-data
	  (if (re-search-backward sh-here-doc-re (point-min) t) 
	      (match-string 1))))))
;;
;; cperl-mode
;;
(defun cperl-here-doc-region ()
  "Return here document region around the point.
Return nil if the point is not in a here document region."
  (let ((pos (point)))
    (if (eq 'here-doc  (get-text-property pos 'syntax-type))
	(let ((b (previous-single-property-change pos 'syntax-type))
	      (e (next-single-property-change pos 'syntax-type)))
	  (setq b (if b b (point-min)))
	  (setq e (if e (1- e) (point-max)))
	  (cons b e)))))

(defun cperl-here-doc-delim ()
  "Return the delimiter of here document region around the point.
Return nil if the point is not in a here document region. 
'EOF' is a typical delimiter. "
  (when (eq 'here-doc  (get-text-property (point) 'syntax-type))
    (let* ((b (next-single-property-change (point) 'syntax-type))
	   (e (if b (next-single-property-change b 'syntax-type))))      
      (when b
	(if e
	    (buffer-substring b e)
	  (buffer-substring b (point-max)))))))

(provide 'hdoc)
;; hdoc.el ends here