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