lisp/generic.el

   1 ;;; generic.el --- defining simple major modes with comment and font-lock
   2 ;;
   3 ;; Copyright (C) 1997, 1999, 2004 Free Software Foundation, Inc.
   4 ;;
   5 ;; Author:  Peter Breton <pbreton@cs.umb.edu>
   6 ;; Created: Fri Sep 27 1996
   7 ;; Keywords: generic, comment, font-lock
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  24 ;; Boston, MA 02111-1307, USA.
  25
  26 ;; Purpose:
  27
  28 ;; Meta-mode to create simple major modes
  29 ;; with basic comment and font-lock support
  30
  31 ;;; Commentary:
  32
  33 ;; INTRODUCTION:
  34
  35 ;; Generic-mode is a meta-mode which can be used to define small modes
  36 ;; which provide basic comment and font-lock support.  These modes are
  37 ;; intended for the many configuration files and such which are too small
  38 ;; for a "real" mode, but still have a regular syntax, comment characters
  39 ;; and the like.
  40 ;;
  41 ;; Each generic mode can define the following:
  42 ;;
  43 ;; * List of comment-characters.  The entries in this list should be
  44 ;;   either a character, a one or two character string or a cons pair.
  45 ;;   If the entry is a character or a one-character string
  46 ;;   LIMITATIONS:  Emacs does not support comment strings of more than
  47 ;;   two characters in length.
  48 ;;
  49 ;; * List of keywords to font-lock.  Each keyword should be a string.
  50 ;;   If you have additional keywords which should be highlighted in a face
  51 ;;   different from `font-lock-keyword-face', you can use the convenience
  52 ;;   function `generic-make-keywords-list' (which see), and add the
  53 ;;   result to the following list:
  54 ;;
  55 ;; * Additional expressions to font-lock.  This should be a list of
  56 ;;   expressions, each of which should be of the same form
  57 ;;   as those in `font-lock-keywords'.
  58 ;;
  59 ;; * List of regular expressions to be placed in auto-mode-alist.
  60 ;;
  61 ;; * List of functions to call to do some additional setup
  62 ;;
  63 ;; This should pretty much cover basic functionality; if you need much
  64 ;; more than this, or you find yourself writing extensive customizations,
  65 ;; perhaps you should be writing a major mode instead!
  66 ;;
  67 ;; LOCAL VARIABLES:
  68 ;;
  69 ;; To put a file into generic mode using local variables, use a line
  70 ;; like this in a Local Variables block:
  71 ;;
  72 ;;   mode: default-generic
  73 ;;
  74 ;; Do NOT use "mode: generic"!
  75 ;; See also "AUTOMATICALLY ENTERING GENERIC MODE" below.
  76 ;;
  77 ;; DEFINING NEW GENERIC MODES:
  78 ;;
  79 ;; Use the `define-generic-mode' function to define new modes.
  80 ;; For example:
  81 ;;
  82 ;;   (require 'generic)
  83 ;;   (define-generic-mode 'foo-generic-mode
  84 ;;                        (list ?% )
  85 ;;                        (list "keyword")
  86 ;;                        nil
  87 ;;                        (list "\\.FOO\\'")
  88 ;;                        (list 'foo-setup-function))
  89 ;;
  90 ;; defines a new generic-mode `foo-generic-mode', which has '%' as a
  91 ;; comment character, and "keyword" as a keyword. When files which end in
  92 ;; '.FOO' are loaded, Emacs will go into foo-generic-mode and call
  93 ;; foo-setup-function.  You can also use the function `foo-generic-mode'
  94 ;; (which is interactive) to put a buffer into foo-generic-mode.
  95 ;;
  96 ;; AUTOMATICALLY ENTERING GENERIC MODE:
  97 ;;
  98 ;; Generic-mode provides a hook which automatically puts a
  99 ;; file into default-generic-mode if the first few lines of a file in
 100 ;; fundamental mode start with a hash comment character. To disable
 101 ;; this functionality, set the variable `generic-use-find-file-hook'
 102 ;; to nil BEFORE loading generic-mode. See the variables
 103 ;; `generic-lines-to-scan' and `generic-find-file-regexp' for customization
 104 ;; options.
 105 ;;
 106 ;; GOTCHAS:
 107 ;;
 108 ;; Be careful that your font-lock definitions are correct.  Getting them
 109 ;; wrong can cause emacs to continually attempt to fontify! This problem
 110 ;; is not specific to generic-mode.
 111 ;;
 112
 113 ;; Credit for suggestions, brainstorming, help with debugging:
 114 ;;   ACorreir@pervasive-sw.com (Alfred Correira)
 115 ;; Extensive cleanup by:
 116 ;;   Stefan Monnier (monnier+gnu/emacs@flint.cs.yale.edu)
 117 ;;
 118 ;;; Code:
 119
 120 (eval-when-compile
 121   (require 'cl))
 122
 123 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 124 ;; Internal Variables
 125 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 126
 127 (defvar generic-font-lock-defaults nil
 128   "Global defaults for font-lock in a generic mode.")
 129 (make-variable-buffer-local 'generic-font-lock-defaults)
 130
 131 (defvar generic-mode-list nil
 132   "A list of mode names for `generic-mode'.
 133 Do not add entries to this list directly; use `define-generic-mode'
 134 instead (which see).")
 135
 136 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 137 ;; Customization Variables
 138 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 139
 140 (defgroup generic nil
 141   "Define simple major modes with comment and font-lock support."
 142   :prefix "generic-"
 143   :group 'extensions)
 144
 145 (defcustom generic-use-find-file-hook t
 146   "*If non-nil, add a hook to enter default-generic-mode automatically.
 147 This is done if the first few lines of a file in fundamental mode start
 148 with a hash comment character."
 149   :group 'generic
 150   :type  'boolean
 151   )
 152
 153 (defcustom generic-lines-to-scan 3
 154   "*Number of lines that `generic-mode-find-file-hook' looks at.
 155 Relevant when deciding whether to enter `generic-mode' automatically.
 156 This variable should be set to a small positive number."
 157   :group 'generic
 158   :type  'integer
 159   )
 160
 161 (defcustom generic-find-file-regexp "^#"
 162   "*Regular expression used by `generic-mode-find-file-hook'.
 163 Files in fundamental mode whose first few lines contain a match for
 164 this regexp, should be put into `default-generic-mode' instead.
 165 The number of lines tested for the matches is specified by the value
 166 of the variable `generic-lines-to-scan', which see."
 167   :group 'generic
 168   :type  'regexp
 169   )
 170
 171 (defcustom generic-ignore-files-regexp "[Tt][Aa][Gg][Ss]\\'"
 172   "*Regular expression used by `generic-mode-find-file-hook'.
 173 Files whose names match this regular expression should not be put
 174 into `default-generic-mode', even if they have lines which match the
 175 regexp in `generic-find-file-regexp'.  If the value is nil,
 176 `generic-mode-find-file-hook' does not check the file names."
 177   :group 'generic
 178   :type  '(choice (const :tag "Don't check file names" nil) regexp)
 179   )
 180
 181 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 182 ;; Functions
 183 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 184
 185 ;;;###autoload
 186 (defun define-generic-mode (name comment-list    keyword-list   font-lock-list
 187                                  auto-mode-list  function-list
 188                                  &optional description)
 189   "Create a new generic mode with NAME.
 190
 191 NAME should be a symbol; its string representation is used as the function
 192 name. If DESCRIPTION is provided, it is used as the docstring for the new
 193 function.
 194
 195 COMMENT-LIST is a list, whose entries are either a single character,
 196 a one or two character string or a cons pair. If the entry is a character
 197 or a one-character string, it is added to the mode's syntax table with
 198 `comment-start' syntax.  If the entry is a cons pair, the elements of the
 199 pair are considered to be `comment-start' and `comment-end' respectively.
 200 Note that Emacs has limitations regarding comment characters.
 201
 202 KEYWORD-LIST is a list of keywords to highlight with `font-lock-keyword-face'.
 203 Each keyword should be a string.
 204
 205 FONT-LOCK-LIST is a list of additional expressions to highlight. Each entry
 206 in the list should have the same form as an entry in `font-lock-keywords'.
 207
 208 AUTO-MODE-LIST is a list of regular expressions to add to `auto-mode-alist'.
 209 These regexps are added to `auto-mode-alist' as soon as `define-generic-mode'
 210 is called; any old regexps with the same name are removed.
 211
 212 FUNCTION-LIST is a list of functions to call to do some additional setup.
 213
 214 See the file generic-x.el for some examples of `define-generic-mode'."
 215
 216   ;; Add a new entry
 217   (unless (assq name generic-mode-list)
 218     (push (list (symbol-name name)) generic-mode-list))
 219
 220   ;; Add it to auto-mode-alist
 221   (dolist (re auto-mode-list)
 222     (add-to-list 'auto-mode-alist (cons re name)))
 223
 224   ;; Define a function for it using `defalias' (not `fset') to make
 225   ;; the mode appear on load-history.
 226   (defalias name
 227     `(lambda nil
 228        ,(or description (concat "Generic mode for type " (symbol-name name)))
 229        (interactive)
 230        (generic-mode-internal ',name ',comment-list ',keyword-list
 231                               ',font-lock-list ',function-list)))
 232   )
 233
 234 (defun generic-mode-internal (mode comments keywords font-lock-list funs)
 235   "Go into the generic-mode MODE."
 236   (let* ((generic-mode-hooks (intern (concat (symbol-name mode) "-hook")))
 237          (modename (symbol-name mode))
 238          (name (if (string-match "-mode\\'" modename)
 239                    (substring modename 0 (match-beginning 0))
 240                  modename))
 241          )
 242
 243     ;; Put this after the point where we read generic-mode-name!
 244     (kill-all-local-variables)
 245
 246     (setq
 247      major-mode                    mode
 248      mode-name                     (capitalize name)
 249      )
 250
 251     (generic-mode-set-comments     comments)
 252
 253     ;; Font-lock functionality
 254     ;; Font-lock-defaults are always set even if there are no keywords
 255     ;; or font-lock expressions, so comments can be highlighted.
 256     (setq generic-font-lock-defaults nil)
 257     (generic-mode-set-font-lock      keywords font-lock-list)
 258     (make-local-variable            'font-lock-defaults)
 259     (setq font-lock-defaults (list 'generic-font-lock-defaults nil))
 260
 261     ;; Call a list of functions
 262     (mapcar 'funcall funs)
 263
 264     (run-hooks generic-mode-hooks)
 265     )
 266   )
 267
 268 ;;;###autoload
 269 (defun generic-mode (type)
 270   "Basic comment and font-lock functionality for `generic' files.
 271 \(Files which are too small to warrant their own mode, but have
 272 comment characters, keywords, and the like.)
 273
 274 To define a generic-mode, use the function `define-generic-mode'.
 275 Some generic modes are defined in `generic-x.el'."
 276   (interactive
 277    (list (completing-read "Generic Type: " generic-mode-list nil t)))
 278   (funcall (intern type)))
 279
 280 ;;; Comment Functionality
 281 (defun generic-mode-set-comments (comment-list)
 282   "Set up comment functionality for generic mode."
 283   (let ((st (make-syntax-table))
 284         (chars nil)
 285         (comstyles))
 286     (make-local-variable             'comment-start)
 287     (make-local-variable             'comment-start-skip)
 288     (make-local-variable             'comment-end)
 289
 290     ;; Go through all the comments
 291     (dolist (start comment-list)
 292       (let ((end ?\n) (comstyle ""))
 293         ;; Normalize
 294         (when (consp start)
 295           (setq end (or (cdr start) end))
 296           (setq start (car start)))
 297         (when (char-valid-p start) (setq start (char-to-string start)))
 298         (when (char-valid-p end)   (setq end (char-to-string end)))
 299
 300         ;; Setup the vars for `comment-region'
 301         (if comment-start
 302             ;; We have already setup a comment-style, so use style b
 303             (progn
 304               (setq comstyle "b")
 305               (setq comment-start-skip
 306                     (concat comment-start-skip "\\|" (regexp-quote start) "+\\s-*")))
 307           ;; First comment-style
 308           (setq comment-start start)
 309           (setq comment-end (if (string-equal end "\n") "" end))
 310           (setq comment-start-skip (concat (regexp-quote start) "+\\s-*")))
 311
 312        ;; Reuse comstyles if necessary
 313        (setq comstyle
 314              (or (cdr (assoc start comstyles))
 315                  (cdr (assoc end comstyles))
 316                  comstyle))
 317        (push (cons start comstyle) comstyles)
 318        (push (cons end comstyle) comstyles)
 319
 320         ;; Setup the syntax table
 321         (if (= (length start) 1)
 322             (modify-syntax-entry (string-to-char start)
 323                                  (concat "< " comstyle) st)
 324           (let ((c0 (elt start 0)) (c1 (elt start 1)))
 325             ;; Store the relevant info but don't update yet
 326             (push (cons c0 (concat (cdr (assoc c0 chars)) "1")) chars)
 327             (push (cons c1 (concat (cdr (assoc c1 chars))
 328                                    (concat "2" comstyle))) chars)))
 329         (if (= (length end) 1)
 330             (modify-syntax-entry (string-to-char end)
 331                                  (concat ">" comstyle) st)
 332           (let ((c0 (elt end 0)) (c1 (elt end 1)))
 333             ;; Store the relevant info but don't update yet
 334             (push (cons c0 (concat (cdr (assoc c0 chars))
 335                                    (concat "3" comstyle))) chars)
 336             (push (cons c1 (concat (cdr (assoc c1 chars)) "4")) chars)))))
 337
 338     ;; Process the chars that were part of a 2-char comment marker
 339     (dolist (cs (nreverse chars))
 340       (modify-syntax-entry (car cs)
 341                            (concat (char-to-string (char-syntax (car cs)))
 342                                    " " (cdr cs))
 343                            st))
 344     (set-syntax-table st)))
 345
 346 (defun generic-mode-set-font-lock (keywords font-lock-expressions)
 347   "Set up font-lock functionality for generic mode."
 348   (setq generic-font-lock-defaults
 349         (append
 350          (when keywords
 351            (list (generic-make-keywords-list keywords font-lock-keyword-face)))
 352          font-lock-expressions)))
 353
 354 ;; Support for [KEYWORD] constructs found in INF, INI and Samba files
 355 (defun generic-bracket-support ()
 356   (setq imenu-generic-expression
 357         '((nil "^\\[\\(.*\\)\\]" 1))
 358         imenu-case-fold-search t))
 359
 360 ;; This generic mode is always defined
 361 (define-generic-mode 'default-generic-mode (list ?#)  nil nil nil nil)
 362
 363 ;; A more general solution would allow us to enter generic-mode for
 364 ;; *any* comment character, but would require us to synthesize a new
 365 ;; generic-mode on the fly. I think this gives us most of what we
 366 ;; want.
 367 (defun generic-mode-find-file-hook ()
 368   "Hook function to enter `default-generic-mode' automatically.
 369 Done if the first few lines of a file in `fundamental-mode' start with
 370 a match for the regexp in `generic-find-file-regexp', unless the
 371 file's name matches the regexp which is the value of the variable
 372 `generic-ignore-files-regexp'.
 373 This hook will be installed if the variable
 374 `generic-use-find-file-hook' is non-nil.  The variable
 375 `generic-lines-to-scan' determines the number of lines to look at."
 376   (when (and (eq major-mode 'fundamental-mode)
 377              (or (null generic-ignore-files-regexp)
 378                  (not (string-match
 379                        generic-ignore-files-regexp
 380                        (file-name-sans-versions buffer-file-name)))))
 381     (save-excursion
 382       (goto-char (point-min))
 383       (when (re-search-forward generic-find-file-regexp
 384                                (save-excursion
 385                                  (forward-line generic-lines-to-scan)
 386                                  (point)) t)
 387         (goto-char (point-min))
 388         (default-generic-mode)))))
 389
 390 (defun generic-mode-ini-file-find-file-hook ()
 391   "Hook function to enter default-generic-mode automatically for INI files.
 392 Done if the first few lines of a file in `fundamental-mode' look like an
 393 INI file.  This hook is NOT installed by default."
 394   (and (eq major-mode 'fundamental-mode)
 395        (save-excursion
 396          (goto-char (point-min))
 397          (and (looking-at "^\\s-*\\[.*\\]")
 398               (ini-generic-mode)))))
 399
 400 (and generic-use-find-file-hook
 401     (add-hook 'find-file-hooks 'generic-mode-find-file-hook))
 402
 403 (defun generic-make-keywords-list (keywords-list face &optional prefix suffix)
 404   "Return a regular expression matching the specified KEYWORDS-LIST.
 405 The regexp is highlighted with FACE."
 406   (unless (listp keywords-list)
 407     (error "Keywords argument must be a list of strings"))
 408   (list (concat prefix "\\_<"
 409                 ;; Use an optimized regexp.
 410                 (regexp-opt keywords-list t)
 411                 "\\_>" suffix)
 412         1
 413         face))
 414
 415 (provide 'generic)
 416
 417 ;;; arch-tag: 239c1fc4-1303-48d9-9ac0-657d655669ea
 418 ;;; generic.el ends here