lisp/generic.el

   1 ;;; generic.el --- Defining simple major modes with comment and font-lock.
   2 ;;
   3 ;; Copyright (C) 1997 Free Software Foundation, Inc.
   4 ;;
   5 ;; Author:  Peter Breton <pbreton@i-kinetics.com>
   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-defaults-alist'.
  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-mode)
  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
 116 ;;; Code:
 117
 118 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 119 ;; Internal Variables
 120 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 121
 122 (make-variable-buffer-local
 123 (defvar generic-font-lock-defaults nil
 124   "Global defaults for font-lock in a generic mode."))
 125
 126 (make-variable-buffer-local
 127 (defvar generic-mode-name 'default-generic-mode
 128   "The name of the generic mode.
 129 This is the car of one of the items in `generic-mode-alist'.
 130 This variable is buffer-local."))
 131
 132 (make-variable-buffer-local
 133 (defvar generic-comment-list nil
 134   "List of comment characters for a generic mode."))
 135
 136 (make-variable-buffer-local
 137 (defvar generic-keywords-list nil
 138   "List of keywords for a generic mode."))
 139
 140 (make-variable-buffer-local
 141 (defvar generic-font-lock-expressions nil
 142   "List of font-lock expressions for a generic mode."))
 143
 144 (make-variable-buffer-local
 145 (defvar generic-mode-function-list nil
 146   "List of customization functions to call for a generic mode."))
 147
 148 (make-variable-buffer-local
 149 (defvar generic-mode-syntax-table nil
 150   "Syntax table for use in a generic mode."))
 151
 152 (defvar generic-mode-alist nil
 153   "An association list for generic-mode.
 154 Each entry in the list looks like this:
 155
 156  NAME COMMENT-LIST KEYWORD-LIST FONT-LOCK-LIST AUTO-MODE-LIST FUNCTION-LIST.
 157
 158 Do not add entries to this list directly; use `define-generic-mode'
 159 instead (which see).")
 160
 161 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 162 ;; Customization Variables
 163 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 164
 165 (defcustom generic-use-find-file-hook t
 166   "*If non-nil, add a hook to enter default-generic-mode automatically
 167 if the first few lines of a file in fundamental mode start with a hash
 168 comment character."
 169   :group 'generic
 170   :type  'boolean
 171   )
 172
 173 (defcustom generic-lines-to-scan 3
 174   "*Number of lines that `generic-mode-find-file-hook' looks at
 175 when deciding whether to enter generic-mode automatically.
 176 This variable should be set to a small positive number."
 177   :group 'generic
 178   :type  'integer
 179   )
 180
 181 (defcustom generic-find-file-regexp "#.*\n\\(.*\n\\)?"
 182   "*Regular expression used by `generic-mode-find-file-hook'
 183 to determine if files in fundamental mode should be put into
 184 `default-generic-mode' instead."
 185   :group 'generic
 186   :type  'regexp
 187   )
 188
 189 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 190 ;; Inline functions
 191 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 192
 193 (defsubst generic-read-type ()
 194   (completing-read
 195    "Generic Type: "
 196    (mapcar
 197     '(lambda (elt) (list (symbol-name (car elt))))
 198     generic-mode-alist) nil t))
 199
 200 ;; Basic sanity checks. It does *not* check whether the elements of the lists
 201 ;; are of the correct type.
 202 (defsubst generic-mode-sanity-check (name comment-list   keyword-list
 203                                           font-lock-list auto-mode-list
 204                                           function-list  &optional description)
 205   (and (not (symbolp name))
 206       (error "%s is not a symbol" (princ name)))
 207
 208   (mapcar '(lambda (elt)
 209              (if (not (listp elt))
 210                  (error "%s is not a list" (princ elt))))
 211           (list comment-list   keyword-list font-lock-list
 212                 auto-mode-list function-list))
 213
 214   (and (not (or (null description) (stringp description)))
 215       (error "Description must be a string or nil"))
 216 )
 217
 218 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 219 ;; Functions
 220 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 221
 222 ;;;### autoload
 223 (defun define-generic-mode (name comment-list    keyword-list   font-lock-list
 224                                  auto-mode-list  function-list
 225                                  &optional description)
 226   "Create a new generic mode with NAME.
 227 NAME should be a symbol; its string representation is used as the function
 228 name. If DESCRIPTION is provided, it is used as the docstring for the new
 229 function.
 230
 231 COMMENT-LIST is a list, whose entries are either a single character,
 232 a one or two character string or a cons pair. If the entry is a character
 233 or a one-character string, it is added to the mode's syntax table with
 234 comment-start syntax. If the entry is a cons pair, the elements of the
 235 pair are considered to be comment-start and comment-end respectively.
 236 Note that Emacs has limitations regarding comment characters.
 237
 238 KEYWORD-LIST is a list of keywords to highlight with `font-lock-keyword-face'.
 239 Each keyword should be a string.
 240
 241 FONT-LOCK-LIST is a list of additional expressions to highlight. Each entry
 242 in the list should have the same form as an entry in `font-lock-defaults-alist'
 243
 244 AUTO-MODE-LIST is a list of regular expressions to add to auto-mode-alist.
 245 These regexps are added to auto-mode-alist as soon as `define-generic-mode'
 246 is called; any old regexps with the same name are removed.
 247
 248 FUNCTION-LIST is a list of functions to call to do some additional setup.
 249
 250 See the file generic-x.el for some examples of `define-generic-mode'."
 251
 252   ;; Basic sanity check
 253   (generic-mode-sanity-check name
 254                              comment-list    keyword-list   font-lock-list
 255                              auto-mode-list  function-list  description)
 256
 257   ;; Remove any old entry
 258   (setq generic-mode-alist
 259         (delq (assq name generic-mode-alist)
 260               generic-mode-alist))
 261
 262   ;; Add a new entry
 263   (setq generic-mode-alist
 264         (append
 265          (list
 266           (list
 267            name comment-list keyword-list font-lock-list
 268            auto-mode-list    function-list
 269            ))
 270          generic-mode-alist))
 271
 272   ;; Add it to auto-mode-alist
 273   (generic-add-to-auto-mode name auto-mode-list t)
 274
 275   ;; Define a function for it
 276   (generic-create-generic-function name description)
 277   )
 278
 279 (defun generic-add-to-auto-mode (mode auto-mode-list
 280                                       &optional remove-old prepend)
 281   "Add the entries for mode to `auto-mode-alist'.
 282 If remove-old is non-nil, removes old entries first. If prepend is
 283 non-nil, prepends entries to auto-mode-alist; otherwise, appends them."
 284
 285   (if (not (listp auto-mode-list))
 286       (error "%s is not a list" (princ auto-mode-list)))
 287
 288   (let ((new-mode (intern (symbol-name mode))))
 289     (and remove-old
 290          (let ((auto-mode-entry))
 291            (while (setq auto-mode-entry (rassq new-mode auto-mode-alist))
 292              (setq auto-mode-alist
 293                    (delq auto-mode-entry
 294                          auto-mode-alist)))))
 295
 296     (mapcar '(lambda (entry)
 297                (generic-add-auto-mode-entry new-mode entry prepend))
 298             auto-mode-list)))
 299
 300 (defun generic-add-auto-mode-entry (name entry &optional prepend)
 301   "Add a new entry to the end of auto-mode-alist.
 302 If prepend is non-nil, add the entry to the front of the list."
 303   (let ((new-entry (list (cons entry name))))
 304     (setq auto-mode-alist
 305           (if prepend
 306               (append new-entry auto-mode-alist)
 307             (append auto-mode-alist new-entry)))))
 308
 309 (defun generic-create-generic-function (name &optional description)
 310   "Create a generic mode function with NAME.
 311 If DESCRIPTION is provided, it is used as the docstring."
 312   (let ((symname (symbol-name name)))
 313     (fset (intern symname)
 314           (list 'lambda nil
 315                 (or description
 316                     (concat "Generic mode for type " symname))
 317                 (list 'interactive)
 318                 (list 'generic-mode-with-type (list 'quote name))))))
 319
 320 (defun generic-mode-with-type (&optional mode)
 321   "Go into the generic-mode MODE."
 322   (let* ((type (or mode generic-mode-name))
 323          (generic-mode-list  (assoc type generic-mode-alist))
 324          )
 325
 326     (and (not generic-mode-list)
 327          (error "Can't find generic-mode information for type %s"
 328                 (princ generic-mode-name)))
 329
 330     ;; Put this after the point where we read generic-mode-name!
 331     (kill-all-local-variables)
 332
 333     (setq
 334      generic-mode-name             type
 335      generic-comment-list          (nth 1 generic-mode-list)
 336      generic-keywords-list         (nth 2 generic-mode-list)
 337      generic-font-lock-expressions (nth 3 generic-mode-list)
 338      generic-mode-function-list    (nth 5 generic-mode-list)
 339      major-mode                    'generic-mode
 340      mode-name                     (symbol-name type)
 341      )
 342
 343     (generic-mode-set-comments     generic-comment-list)
 344
 345     ;; Font-lock functionality
 346     ;; Font-lock-defaults are always set even if there are no keywords
 347     ;; or font-lock expressions, so comments can be highlighted.
 348     (setq generic-font-lock-defaults nil)
 349     (generic-mode-set-font-lock      generic-keywords-list
 350                                      generic-font-lock-expressions)
 351     (make-local-variable            'font-lock-defaults)
 352     (setq font-lock-defaults (list 'generic-font-lock-defaults nil))
 353
 354     ;; Call a list of functions
 355     (and generic-mode-function-list
 356          (mapcar 'funcall generic-mode-function-list))
 357     )
 358   )
 359
 360 ;;;###autoload
 361 (defun generic-mode (type)
 362   "A mode to do basic comment and font-lock functionality
 363 for files which are too small to warrant their own mode, but have
 364 comment characters, keywords, and the like.
 365
 366 To define a generic-mode, use the function `define-generic-mode'.
 367 Some generic modes are defined in `generic-x.el'."
 368   (interactive
 369    (list (generic-read-type)))
 370   (generic-mode-with-type (intern type)))
 371
 372 ;;; Comment Functionality
 373 (defun generic-mode-set-comments (comment-list)
 374   "Set up comment functionality for generic mode."
 375   (if (null comment-list)
 376       nil
 377     (let ((generic-mode-syntax-table (make-syntax-table)))
 378       (make-local-variable           'comment-start)
 379       (make-local-variable           'comment-start-skip)
 380       (make-local-variable           'comment-end)
 381       (mapcar 'generic-mode-set-a-comment comment-list)
 382       (set-syntax-table    generic-mode-syntax-table))))
 383
 384 (defun generic-mode-set-a-comment (comment)
 385   (and (char-or-string-p comment)
 386        (if (stringp comment)
 387            (cond
 388             ((eq (length comment) 1)
 389              (generic-mode-set-comment-char
 390               (string-to-char comment)))
 391             ((eq (length comment) 2)
 392              (generic-mode-set-comment-string comment))
 393             (t
 394              (error "Character string %s must be one or two characters long"
 395                     comment))
 396             )
 397          (generic-mode-set-comment-char comment)))
 398   (and (consp comment)
 399        (generic-mode-set-comment-pair comment)))
 400
 401 (defun generic-mode-set-comment-char (comment-char)
 402   "Set the given character as a comment character for generic mode."
 403   (if (not comment-char)
 404       nil
 405     (setq
 406      comment-end         ""
 407      comment-start       (char-to-string comment-char)
 408      comment-start-skip  (concat comment-start "+ *")
 409      )
 410
 411     (modify-syntax-entry comment-char "<"
 412                          generic-mode-syntax-table)
 413     (modify-syntax-entry ?\n ">"
 414                          generic-mode-syntax-table)))
 415
 416 (defun generic-mode-set-comment-string (comment-string)
 417   "Set the given string as a comment string for generic mode."
 418   (if (not comment-string)
 419       nil
 420     (setq
 421      comment-end         ""
 422      comment-start       comment-string
 423      comment-start-skip  (concat comment-start " *")
 424      )
 425
 426     (let ((first  (elt comment-string 0))
 427           (second (elt comment-string 1)))
 428       ;; C++ style comments
 429       (if (char-equal first second)
 430           (progn
 431             (modify-syntax-entry first "<12b"
 432                                  generic-mode-syntax-table)
 433             (modify-syntax-entry ?\n ">b"
 434                                  generic-mode-syntax-table)))
 435       ;; Some other two character string
 436       (modify-syntax-entry first  "<1"
 437                            generic-mode-syntax-table)
 438       (modify-syntax-entry second "<2"
 439                            generic-mode-syntax-table)
 440       (modify-syntax-entry ?\n ">"
 441                            generic-mode-syntax-table))))
 442
 443 (defun generic-mode-set-comment-pair (comment-pair)
 444   "Set the given comment pair as a comment start and end for generic mode."
 445   (let ((generic-comment-start (car comment-pair))
 446         (generic-comment-end   (cdr comment-pair))
 447         )
 448     (setq
 449      comment-end         generic-comment-end
 450      comment-start       generic-comment-start
 451      comment-start-skip  (concat generic-comment-start " *")
 452      )
 453
 454     ;; Sanity checks
 455     (and (not (and (stringp generic-comment-start)
 456                    (stringp generic-comment-end)))
 457          (error "Elements of cons pair must be strings"))
 458     (and (not (and (equal (length generic-comment-start) 2)
 459                    (equal (length generic-comment-end) 2)))
 460         (error "Start and end must be exactly two characters long"))
 461
 462     (let ((first   (elt generic-comment-start 0))
 463           (second  (elt generic-comment-start 1))
 464           (third   (elt generic-comment-end   0))
 465           (fourth  (elt generic-comment-end   1))
 466           )
 467
 468       (modify-syntax-entry first   ". 1" generic-mode-syntax-table)
 469       (modify-syntax-entry second  ". 2" generic-mode-syntax-table)
 470
 471       (modify-syntax-entry
 472        third
 473        (concat
 474         "."
 475         (cond
 476          ((char-equal first   third) " 13")
 477          ((char-equal second  third) " 23")
 478          (t                          " 3"))
 479         )
 480        generic-mode-syntax-table)
 481
 482       (modify-syntax-entry
 483        fourth
 484        (concat
 485         "."
 486         (cond
 487          ((char-equal first   fourth) " 14")
 488          ((char-equal second  fourth) " 24")
 489          (t                           " 4"))
 490         )
 491        generic-mode-syntax-table)
 492       )))
 493
 494 (defun generic-mode-set-font-lock (keywords font-lock-expressions)
 495   "Set up font-lock functionality for generic mode."
 496   (let ((generic-font-lock-expressions))
 497     ;; Keywords
 498     (and keywords
 499         (setq
 500          generic-font-lock-expressions
 501          (append
 502           (list
 503            (list
 504             (concat
 505              "\\(\\<"
 506              (mapconcat 'identity keywords "\\>\\|\\<")
 507              "\\>\\)")
 508             1 'font-lock-keyword-face))
 509           generic-font-lock-expressions)))
 510     ;; Other font-lock expressions
 511     (and font-lock-expressions
 512         (setq generic-font-lock-expressions
 513               (append
 514                font-lock-expressions
 515                generic-font-lock-expressions)))
 516     (and (or font-lock-expressions keywords)
 517          (setq generic-font-lock-defaults generic-font-lock-expressions))
 518     ))
 519
 520 ;; Support for [KEYWORD] constructs found in INF, INI and Samba files
 521 (defun generic-bracket-support ()
 522   (setq imenu-generic-expression
 523         '((nil "^\\[\\(.*\\)\\]" 1))
 524         imenu-case-fold-search t))
 525
 526 ;; This generic mode is always defined
 527 (define-generic-mode 'default-generic-mode (list ?#)  nil nil nil nil)
 528
 529 ;; A more general solution would allow us to enter generic-mode for
 530 ;; *any* comment character, but would require us to synthesize a new
 531 ;; generic-mode on the fly. I think this gives us most of what we
 532 ;; want.
 533 (defun generic-mode-find-file-hook ()
 534   "Hook to enter default-generic-mode automatically
 535 if the first few lines of a file in fundamental-mode start with a hash
 536 comment character. This hook will be installed if the variable
 537 `generic-use-find-file-hook' is non-nil. The variable `generic-lines-to-scan'
 538 determines the number of lines to look at."
 539   (if (not (eq major-mode 'fundamental-mode))
 540       nil
 541     (and (or (> 1  generic-lines-to-scan)
 542              (< 50 generic-lines-to-scan))
 543          (error "Variable `generic-lines-to-scan' should be set to a small"
 544                 " positive number"))
 545     (let ((comment-regexp "")
 546           (count 0)
 547           )
 548       (while (< count generic-lines-to-scan)
 549         (setq comment-regexp (concat comment-regexp
 550                                      generic-find-file-regexp))
 551         (setq count (1+ count)))
 552       (save-excursion
 553         (goto-char (point-min))
 554         (and (looking-at comment-regexp)
 555              (generic-mode-with-type 'default-generic-mode))))))
 556
 557 (defun generic-mode-ini-file-find-file-hook ()
 558   "Hook to enter default-generic-mode automatically
 559 if the first few lines of a file in fundamental-mode look like an INI file.
 560 This hook is NOT installed by default."
 561   (and (eq major-mode 'fundamental-mode)
 562        (save-excursion
 563          (goto-char (point-min))
 564          (and (looking-at "^\\s-*\\[.*\\]")
 565               (generic-mode-with-type 'ini-generic-mode)))))
 566
 567 (and generic-use-find-file-hook
 568     (add-hook 'find-file-hooks 'generic-mode-find-file-hook))
 569
 570 (defun generic-make-keywords-list (keywords-list face &optional prefix suffix)
 571   "Return a regular expression matching the specified keywords.
 572 The regexp is highlighted with FACE."
 573   ;; Sanity checks
 574   ;; Don't check here; face may not be defined yet
 575   ;;   (if (not (facep face))
 576   ;;       (error "Face %s is not defined" (princ face)))
 577   (and (not (listp keywords-list))
 578        (error "Keywords argument must be a list of strings"))
 579   (list
 580    (concat
 581     (or prefix "")
 582     "\\(\\<"
 583     (mapconcat 'identity keywords-list "\\>\\|\\<")
 584     "\\>\\)"
 585     (or suffix "")
 586     ) 1 face))
 587
 588 (provide 'generic)
 589
 590 ;;; generic.el ends here