lisp/generic.el

   1 ;;; generic.el --- defining simple major modes with comment and font-lock
   2 ;;
   3 ;; Copyright (C) 1997, 1999 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 Args: (NAME COMMENT-LIST KEYWORD-LIST FONT-LOCK-LIST AUTO-MODE-LIST
 192             FUNCTION-LIST &optional DESCRIPTION)
 193
 194 NAME should be a symbol; its string representation is used as the function
 195 name. If DESCRIPTION is provided, it is used as the docstring for the new
 196 function.
 197
 198 COMMENT-LIST is a list, whose entries are either a single character,
 199 a one or two character string or a cons pair. If the entry is a character
 200 or a one-character string, it is added to the mode's syntax table with
 201 `comment-start' syntax.  If the entry is a cons pair, the elements of the
 202 pair are considered to be `comment-start' and `comment-end' respectively.
 203 Note that Emacs has limitations regarding comment characters.
 204
 205 KEYWORD-LIST is a list of keywords to highlight with `font-lock-keyword-face'.
 206 Each keyword should be a string.
 207
 208 FONT-LOCK-LIST is a list of additional expressions to highlight. Each entry
 209 in the list should have the same form as an entry in `font-lock-keywords'.
 210
 211 AUTO-MODE-LIST is a list of regular expressions to add to `auto-mode-alist'.
 212 These regexps are added to `auto-mode-alist' as soon as `define-generic-mode'
 213 is called; any old regexps with the same name are removed.
 214
 215 FUNCTION-LIST is a list of functions to call to do some additional setup.
 216
 217 See the file generic-x.el for some examples of `define-generic-mode'."
 218
 219   ;; Add a new entry
 220   (unless (assq name generic-mode-list)
 221     (push (list (symbol-name name)) generic-mode-list))
 222
 223   ;; Add it to auto-mode-alist
 224   (dolist (re auto-mode-list)
 225     (add-to-list 'auto-mode-alist (cons re name)))
 226
 227   ;; Define a function for it using `defalias' (not `fset') to make
 228   ;; the mode appear on load-history.
 229   (defalias name
 230     `(lambda nil
 231        ,(or description (concat "Generic mode for type " (symbol-name name)))
 232        (interactive)
 233        (generic-mode-internal ',name ',comment-list ',keyword-list
 234                               ',font-lock-list ',function-list)))
 235   )
 236
 237 (defun generic-mode-internal (mode comments keywords font-lock-list funs)
 238   "Go into the generic-mode MODE."
 239   (let* ((generic-mode-hooks (intern (concat (symbol-name mode) "-hook")))
 240          (modename (symbol-name mode))
 241          (name (if (string-match "-mode\\'" modename)
 242                    (substring modename 0 (match-beginning 0))
 243                  modename))
 244          )
 245
 246     ;; Put this after the point where we read generic-mode-name!
 247     (kill-all-local-variables)
 248
 249     (setq
 250      major-mode                    mode
 251      mode-name                     (capitalize name)
 252      )
 253
 254     (generic-mode-set-comments     comments)
 255
 256     ;; Font-lock functionality
 257     ;; Font-lock-defaults are always set even if there are no keywords
 258     ;; or font-lock expressions, so comments can be highlighted.
 259     (setq generic-font-lock-defaults nil)
 260     (generic-mode-set-font-lock      keywords font-lock-list)
 261     (make-local-variable            'font-lock-defaults)
 262     (setq font-lock-defaults (list 'generic-font-lock-defaults nil))
 263
 264     ;; Call a list of functions
 265     (mapcar 'funcall funs)
 266
 267     (run-hooks generic-mode-hooks)
 268     )
 269   )
 270
 271 ;;;###autoload
 272 (defun generic-mode (type)
 273   "Basic comment and font-lock functionality for `generic' files.
 274 \(Files which are too small to warrant their own mode, but have
 275 comment characters, keywords, and the like.)
 276
 277 To define a generic-mode, use the function `define-generic-mode'.
 278 Some generic modes are defined in `generic-x.el'."
 279   (interactive
 280    (list (completing-read "Generic Type: " generic-mode-list nil t)))
 281   (funcall (intern type)))
 282
 283 ;;; Comment Functionality
 284 (defun generic-mode-set-comments (comment-list)
 285   "Set up comment functionality for generic mode."
 286   (let ((st (make-syntax-table))
 287         (chars nil)
 288         (comstyles))
 289     (make-local-variable             'comment-start)
 290     (make-local-variable             'comment-start-skip)
 291     (make-local-variable             'comment-end)
 292
 293     ;; Go through all the comments
 294     (dolist (start comment-list)
 295       (let ((end ?\n) (comstyle ""))
 296         ;; Normalize
 297         (when (consp start)
 298           (setq end (or (cdr start) end))
 299           (setq start (car start)))
 300         (when (char-valid-p start) (setq start (char-to-string start)))
 301         (when (char-valid-p end)   (setq end (char-to-string end)))
 302
 303         ;; Setup the vars for `comment-region'
 304         (if comment-start
 305             ;; We have already setup a comment-style, so use style b
 306             (progn
 307               (setq comstyle "b")
 308               (setq comment-start-skip
 309                     (concat comment-start-skip "\\|" (regexp-quote start) "+\\s-*")))
 310           ;; First comment-style
 311           (setq comment-start start)
 312           (setq comment-end (if (string-equal end "\n") "" end))
 313           (setq comment-start-skip (concat (regexp-quote start) "+\\s-*")))
 314
 315        ;; Reuse comstyles if necessary
 316        (setq comstyle
 317              (or (cdr (assoc start comstyles))
 318                  (cdr (assoc end comstyles))
 319                  comstyle))
 320        (push (cons start comstyle) comstyles)
 321        (push (cons end comstyle) comstyles)
 322
 323         ;; Setup the syntax table
 324         (if (= (length start) 1)
 325             (modify-syntax-entry (string-to-char start)
 326                                  (concat "< " comstyle) st)
 327           (let ((c0 (elt start 0)) (c1 (elt start 1)))
 328             ;; Store the relevant info but don't update yet
 329             (push (cons c0 (concat (cdr (assoc c0 chars)) "1")) chars)
 330             (push (cons c1 (concat (cdr (assoc c1 chars))
 331                                    (concat "2" comstyle))) chars)))
 332         (if (= (length end) 1)
 333             (modify-syntax-entry (string-to-char end)
 334                                  (concat ">" comstyle) st)
 335           (let ((c0 (elt end 0)) (c1 (elt end 1)))
 336             ;; Store the relevant info but don't update yet
 337             (push (cons c0 (concat (cdr (assoc c0 chars))
 338                                    (concat "3" comstyle))) chars)
 339             (push (cons c1 (concat (cdr (assoc c1 chars)) "4")) chars)))))
 340
 341     ;; Process the chars that were part of a 2-char comment marker
 342     (dolist (cs (nreverse chars))
 343       (modify-syntax-entry (car cs)
 344                            (concat (char-to-string (char-syntax (car cs)))
 345                                    " " (cdr cs))
 346                            st))
 347     (set-syntax-table st)))
 348
 349 (defun generic-mode-set-font-lock (keywords font-lock-expressions)
 350   "Set up font-lock functionality for generic mode."
 351   (setq generic-font-lock-defaults
 352         (append
 353          (when keywords
 354            (list (generic-make-keywords-list keywords font-lock-keyword-face)))
 355          font-lock-expressions)))
 356
 357 ;; Support for [KEYWORD] constructs found in INF, INI and Samba files
 358 (defun generic-bracket-support ()
 359   (setq imenu-generic-expression
 360         '((nil "^\\[\\(.*\\)\\]" 1))
 361         imenu-case-fold-search t))
 362
 363 ;; This generic mode is always defined
 364 (define-generic-mode 'default-generic-mode (list ?#)  nil nil nil nil)
 365
 366 ;; A more general solution would allow us to enter generic-mode for
 367 ;; *any* comment character, but would require us to synthesize a new
 368 ;; generic-mode on the fly. I think this gives us most of what we
 369 ;; want.
 370 (defun generic-mode-find-file-hook ()
 371   "Hook function to enter `default-generic-mode' automatically.
 372 Done if the first few lines of a file in `fundamental-mode' start with
 373 a match for the regexp in `generic-find-file-regexp', unless the
 374 file's name matches the regexp which is the value of the variable
 375 `generic-ignore-files-regexp'.
 376 This hook will be installed if the variable
 377 `generic-use-find-file-hook' is non-nil.  The variable
 378 `generic-lines-to-scan' determines the number of lines to look at."
 379   (when (and (eq major-mode 'fundamental-mode)
 380              (or (null generic-ignore-files-regexp)
 381                  (not (string-match
 382                        generic-ignore-files-regexp
 383                        (file-name-sans-versions buffer-file-name)))))
 384     (save-excursion
 385       (goto-char (point-min))
 386       (when (re-search-forward generic-find-file-regexp
 387                                (save-excursion
 388                                  (forward-line generic-lines-to-scan)
 389                                  (point)) t)
 390         (goto-char (point-min))
 391         (default-generic-mode)))))
 392
 393 (defun generic-mode-ini-file-find-file-hook ()
 394   "Hook function to enter default-generic-mode automatically for INI files.
 395 Done if the first few lines of a file in `fundamental-mode' look like an
 396 INI file.  This hook is NOT installed by default."
 397   (and (eq major-mode 'fundamental-mode)
 398        (save-excursion
 399          (goto-char (point-min))
 400          (and (looking-at "^\\s-*\\[.*\\]")
 401               (ini-generic-mode)))))
 402
 403 (and generic-use-find-file-hook
 404     (add-hook 'find-file-hooks 'generic-mode-find-file-hook))
 405
 406 (defun generic-make-keywords-list (keywords-list face &optional prefix suffix)
 407   "Return a regular expression matching the specified KEYWORDS-LIST.
 408 The regexp is highlighted with FACE."
 409   (unless (listp keywords-list)
 410     (error "Keywords argument must be a list of strings"))
 411   (list (concat prefix "\\<"
 412                 ;; Use an optimized regexp.
 413                 (regexp-opt keywords-list t)
 414                 "\\>" suffix)
 415         1
 416         face))
 417
 418 (provide 'generic)
 419
 420 ;;; arch-tag: 239c1fc4-1303-48d9-9ac0-657d655669ea
 421 ;;; generic.el ends here