lisp/emacs-lisp/generic.el

   1 ;;; generic.el --- defining simple major modes with comment and font-lock
   2 ;;
   3 ;; Copyright (C) 1997, 1999, 2001, 2002, 2003, 2004,
   4 ;;   2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc.
   5 ;;
   6 ;; Author:  Peter Breton <pbreton@cs.umb.edu>
   7 ;; Created: Fri Sep 27 1996
   8 ;; Keywords: generic, comment, font-lock
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software: you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation, either version 3 of the License, or
  15 ;; (at your option) any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  24
  25 ;;; Commentary:
  26
  27 ;; INTRODUCTION:
  28 ;;
  29 ;; The macro `define-generic-mode' can be used to define small modes
  30 ;; which provide basic comment and font-lock support.  These modes are
  31 ;; intended for the many configuration files and such which are too
  32 ;; small for a "real" mode, but still have a regular syntax, comment
  33 ;; characters and the like.
  34 ;;
  35 ;; Each generic mode can define the following:
  36 ;;
  37 ;; * List of comment-characters.  The elements of this list should be
  38 ;;   either a character, a one or two character string, or a cons
  39 ;;   cell.  If the entry is a character or a string, it is added to
  40 ;;   the mode's syntax table with "comment starter" syntax.  If the
  41 ;;   entry is a cons cell, the `car' and `cdr' of the pair are
  42 ;;   considered the "comment starter" and "comment ender"
  43 ;;   respectively.  (The latter should be nil if you want comments to
  44 ;;   end at the end of the line.)  Emacs does not support comment
  45 ;;   strings of more than two characters in length.
  46 ;;
  47 ;; * List of keywords to font-lock.  Each keyword should be a string.
  48 ;;   If you have additional keywords which should be highlighted in a
  49 ;;   face different from `font-lock-keyword-face', you can use the
  50 ;;   convenience function `generic-make-keywords-list' (which see),
  51 ;;   and add the result to the following list:
  52 ;;
  53 ;; * Additional expressions to font-lock.  This should be a list of
  54 ;;   expressions, each of which should be of the same form as those in
  55 ;;   `font-lock-keywords'.
  56 ;;
  57 ;; * List of regular expressions to be placed in auto-mode-alist.
  58 ;;
  59 ;; * List of functions to call to do some additional setup
  60 ;;
  61 ;; This should pretty much cover basic functionality; if you need much
  62 ;; more than this, or you find yourself writing extensive customizations,
  63 ;; perhaps you should be writing a major mode instead!
  64 ;;
  65 ;; EXAMPLE:
  66 ;;
  67 ;; You can use `define-generic-mode' like this:
  68 ;;
  69 ;;   (define-generic-mode 'foo-generic-mode
  70 ;;     (list ?%)
  71 ;;     (list "keyword")
  72 ;;     nil
  73 ;;     (list "\\.FOO\\'")
  74 ;;     (list 'foo-setup-function))
  75 ;;
  76 ;; to define a new generic-mode `foo-generic-mode', which has '%' as a
  77 ;; comment character, and "keyword" as a keyword.  When files which
  78 ;; end in '.FOO' are loaded, Emacs will go into foo-generic-mode and
  79 ;; call foo-setup-function.  You can also use the function
  80 ;; `foo-generic-mode' (which is interactive) to put a buffer into
  81 ;; foo-generic-mode.
  82 ;;
  83 ;; GOTCHAS:
  84 ;;
  85 ;; Be careful that your font-lock definitions are correct.  Getting
  86 ;; them wrong can cause Emacs to continually attempt to fontify! This
  87 ;; problem is not specific to generic-mode.
  88
  89 ;; Credit for suggestions, brainstorming, help with debugging:
  90 ;;   ACorreir@pervasive-sw.com (Alfred Correira)
  91 ;; Extensive cleanup by:
  92 ;;   Stefan Monnier (monnier+gnu/emacs@flint.cs.yale.edu)
  93
  94 ;;; Code:
  95
  96 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  97 ;; Internal Variables
  98 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  99
 100 (defvar generic-font-lock-keywords nil
 101   "Keywords for `font-lock-defaults' in a generic mode.")
 102 (make-variable-buffer-local 'generic-font-lock-keywords)
 103 (define-obsolete-variable-alias 'generic-font-lock-defaults 'generic-font-lock-keywords "22.1")
 104
 105 ;;;###autoload
 106 (defvar generic-mode-list nil
 107   "A list of mode names for `generic-mode'.
 108 Do not add entries to this list directly; use `define-generic-mode'
 109 instead (which see).")
 110
 111 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 112 ;; Functions
 113 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 114
 115 ;;;###autoload
 116 (defmacro define-generic-mode (mode comment-list keyword-list
 117                                     font-lock-list auto-mode-list
 118                                     function-list &optional docstring)
 119   "Create a new generic mode MODE.
 120
 121 MODE is the name of the command for the generic mode; don't quote it.
 122 The optional DOCSTRING is the documentation for the mode command.  If
 123 you do not supply it, `define-generic-mode' uses a default
 124 documentation string instead.
 125
 126 COMMENT-LIST is a list in which each element is either a character, a
 127 string of one or two characters, or a cons cell.  A character or a
 128 string is set up in the mode's syntax table as a \"comment starter\".
 129 If the entry is a cons cell, the `car' is set up as a \"comment
 130 starter\" and the `cdr' as a \"comment ender\".  (Use nil for the
 131 latter if you want comments to end at the end of the line.)  Note that
 132 the syntax table has limitations about what comment starters and
 133 enders are actually possible.
 134
 135 KEYWORD-LIST is a list of keywords to highlight with
 136 `font-lock-keyword-face'.  Each keyword should be a string.
 137
 138 FONT-LOCK-LIST is a list of additional expressions to highlight.  Each
 139 element of this list should have the same form as an element of
 140 `font-lock-keywords'.
 141
 142 AUTO-MODE-LIST is a list of regular expressions to add to
 143 `auto-mode-alist'.  These regular expressions are added when Emacs
 144 runs the macro expansion.
 145
 146 FUNCTION-LIST is a list of functions to call to do some additional
 147 setup.  The mode command calls these functions just before it runs the
 148 mode hook `MODE-hook'.
 149
 150 See the file generic-x.el for some examples of `define-generic-mode'."
 151   (declare (debug (sexp def-form def-form def-form form def-form
 152                         [&optional stringp] &rest [keywordp form]))
 153            (indent 1))
 154
 155   ;; Backward compatibility.
 156   (when (eq (car-safe mode) 'quote)
 157     (setq mode (eval mode)))
 158
 159   (let* ((name (symbol-name mode))
 160          (pretty-name (capitalize (replace-regexp-in-string
 161                                    "-mode\\'" "" name))))
 162
 163     `(progn
 164        ;; Add a new entry.
 165        (add-to-list 'generic-mode-list ,name)
 166
 167        ;; Add it to auto-mode-alist
 168        (dolist (re ,auto-mode-list)
 169          (add-to-list 'auto-mode-alist (cons re ',mode)))
 170
 171        (defun ,mode ()
 172          ,(or docstring
 173               (concat pretty-name " mode.\n"
 174                       "This a generic mode defined with `define-generic-mode'.\n"
 175                       "It runs `" name "-hook' as the last thing it does."))
 176          (interactive)
 177          (generic-mode-internal ',mode ,comment-list ,keyword-list
 178                                 ,font-lock-list ,function-list)))))
 179
 180 ;;;###autoload
 181 (defun generic-mode-internal (mode comment-list keyword-list
 182                                    font-lock-list function-list)
 183   "Go into the generic mode MODE."
 184   (let* ((name (symbol-name mode))
 185          (pretty-name (capitalize (replace-regexp-in-string
 186                                    "-mode\\'" "" name)))
 187          (mode-hook (intern (concat name "-hook"))))
 188
 189     (kill-all-local-variables)
 190
 191     (setq major-mode mode
 192           mode-name pretty-name)
 193
 194     (generic-mode-set-comments comment-list)
 195
 196     ;; Font-lock functionality.
 197     ;; Font-lock-defaults is always set even if there are no keywords
 198     ;; or font-lock expressions, so comments can be highlighted.
 199     (setq generic-font-lock-keywords font-lock-list)
 200     (when keyword-list
 201       (push (concat "\\_<" (regexp-opt keyword-list t) "\\_>")
 202             generic-font-lock-keywords))
 203     (setq font-lock-defaults '(generic-font-lock-keywords))
 204
 205     ;; Call a list of functions
 206     (mapc 'funcall function-list)
 207
 208     (run-mode-hooks mode-hook)))
 209
 210 ;;;###autoload
 211 (defun generic-mode (mode)
 212   "Enter generic mode MODE.
 213
 214 Generic modes provide basic comment and font-lock functionality
 215 for \"generic\" files.  (Files which are too small to warrant their
 216 own mode, but have comment characters, keywords, and the like.)
 217
 218 To define a generic-mode, use the function `define-generic-mode'.
 219 Some generic modes are defined in `generic-x.el'."
 220   (interactive
 221    (list (completing-read "Generic mode: " generic-mode-list nil t)))
 222   (funcall (intern mode)))
 223
 224 ;;; Comment Functionality
 225 (defun generic-mode-set-comments (comment-list)
 226   "Set up comment functionality for generic mode."
 227   (let ((st (make-syntax-table))
 228         (chars nil)
 229         (comstyles))
 230     (make-local-variable 'comment-start)
 231     (make-local-variable 'comment-start-skip)
 232     (make-local-variable 'comment-end)
 233
 234     ;; Go through all the comments
 235     (dolist (start comment-list)
 236       (let (end (comstyle ""))
 237         ;; Normalize
 238         (when (consp start)
 239           (setq end (cdr start))
 240           (setq start (car start)))
 241         (when (characterp start) (setq start (char-to-string start)))
 242         (cond
 243          ((characterp end)   (setq end (char-to-string end)))
 244          ((zerop (length end)) (setq end "\n")))
 245
 246         ;; Setup the vars for `comment-region'
 247         (if comment-start
 248             ;; We have already setup a comment-style, so use style b
 249             (progn
 250               (setq comstyle "b")
 251               (setq comment-start-skip
 252                     (concat comment-start-skip "\\|" (regexp-quote start) "+\\s-*")))
 253           ;; First comment-style
 254           (setq comment-start start)
 255           (setq comment-end (if (string-equal end "\n") "" end))
 256           (setq comment-start-skip (concat (regexp-quote start) "+\\s-*")))
 257
 258        ;; Reuse comstyles if necessary
 259        (setq comstyle
 260              (or (cdr (assoc start comstyles))
 261                  (cdr (assoc end comstyles))
 262                  comstyle))
 263        (push (cons start comstyle) comstyles)
 264        (push (cons end comstyle) comstyles)
 265
 266         ;; Setup the syntax table
 267         (if (= (length start) 1)
 268             (modify-syntax-entry (string-to-char start)
 269                                  (concat "< " comstyle) st)
 270           (let ((c0 (elt start 0)) (c1 (elt start 1)))
 271             ;; Store the relevant info but don't update yet
 272             (push (cons c0 (concat (cdr (assoc c0 chars)) "1")) chars)
 273             (push (cons c1 (concat (cdr (assoc c1 chars))
 274                                    (concat "2" comstyle))) chars)))
 275         (if (= (length end) 1)
 276             (modify-syntax-entry (string-to-char end)
 277                                  (concat ">" comstyle) st)
 278           (let ((c0 (elt end 0)) (c1 (elt end 1)))
 279             ;; Store the relevant info but don't update yet
 280             (push (cons c0 (concat (cdr (assoc c0 chars))
 281                                    (concat "3" comstyle))) chars)
 282             (push (cons c1 (concat (cdr (assoc c1 chars)) "4")) chars)))))
 283
 284     ;; Process the chars that were part of a 2-char comment marker
 285     (dolist (cs (nreverse chars))
 286       (modify-syntax-entry (car cs)
 287                            (concat (char-to-string (char-syntax (car cs)))
 288                                    " " (cdr cs))
 289                            st))
 290     (set-syntax-table st)))
 291
 292 (defun generic-bracket-support ()
 293   "Imenu support for [KEYWORD] constructs found in INF, INI and Samba files."
 294   (setq imenu-generic-expression
 295         '((nil "^\\[\\(.*\\)\\]" 1))
 296         imenu-case-fold-search t))
 297
 298 ;;;###autoload
 299 (defun generic-make-keywords-list (keyword-list face &optional prefix suffix)
 300   "Return a `font-lock-keywords' construct that highlights KEYWORD-LIST.
 301 KEYWORD-LIST is a list of keyword strings that should be
 302 highlighted with face FACE.  This function calculates a regular
 303 expression that matches these keywords and concatenates it with
 304 PREFIX and SUFFIX.  Then it returns a construct based on this
 305 regular expression that can be used as an element of
 306 `font-lock-keywords'."
 307   (unless (listp keyword-list)
 308     (error "Keywords argument must be a list of strings"))
 309   (list (concat prefix "\\_<"
 310                 ;; Use an optimized regexp.
 311                 (regexp-opt keyword-list t)
 312                 "\\_>" suffix)
 313         1
 314         face))
 315
 316 (provide 'generic)
 317
 318 ;; arch-tag: 239c1fc4-1303-48d9-9ac0-657d655669ea
 319 ;;; generic.el ends here