cperl-mode.el 323 KB
Newer Older
Karl Heuer's avatar
Karl Heuer committed
1 2
;;; cperl-mode.el --- Perl code editing commands for Emacs

Paul Eggert's avatar
Paul Eggert committed
3
;; Copyright (C) 1985-1987, 1991-2017 Free Software Foundation, Inc.
Karl Heuer's avatar
Karl Heuer committed
4

5 6
;; Author: Ilya Zakharevich
;;	Bob Olson
Glenn Morris's avatar
Glenn Morris committed
7
;; Maintainer: emacs-devel@gnu.org
Karl Heuer's avatar
Karl Heuer committed
8 9 10 11
;; Keywords: languages, Perl

;; This file is part of GNU Emacs.

12
;; GNU Emacs is free software: you can redistribute it and/or modify
Karl Heuer's avatar
Karl Heuer committed
13
;; it under the terms of the GNU General Public License as published by
14 15
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
Karl Heuer's avatar
Karl Heuer committed
16 17 18 19 20 21 22

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; 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/>.
Karl Heuer's avatar
Karl Heuer committed
24

25
;;; Corrections made by Ilya Zakharevich ilyaz@cpan.org
Karl Heuer's avatar
Karl Heuer committed
26 27 28

;;; Commentary:

29 30
;; You can either fine-tune the bells and whistles of this mode or
;; bulk enable them by putting
Karl Heuer's avatar
Karl Heuer committed
31 32 33

;; (setq cperl-hairy t)

34 35
;; in your .emacs file.  (Emacs rulers do not consider it politically
;; correct to make whistles enabled by default.)
Karl Heuer's avatar
Karl Heuer committed
36

37 38
;; DO NOT FORGET to read micro-docs (available from `Perl' menu)   <<<<<<
;; or as help on variables `cperl-tips', `cperl-problems',         <<<<<<
39
;; `cperl-praise', `cperl-speed'.				   <<<<<<
Karl Heuer's avatar
Karl Heuer committed
40

41 42 43
;; The mode information (on C-h m) provides some customization help.
;; If you use font-lock feature of this mode, it is advisable to use
;; either lazy-lock-mode or fast-lock-mode.  I prefer lazy-lock.
Karl Heuer's avatar
Karl Heuer committed
44

45 46 47 48 49
;; Faces used now: three faces for first-class and second-class keywords
;; and control flow words, one for each: comments, string, labels,
;; functions definitions and packages, arrays, hashes, and variable
;; definitions.  If you do not see all these faces, your font-lock does
;; not define them, so you need to define them manually.
Karl Heuer's avatar
Karl Heuer committed
50

51 52 53 54 55
;; This mode supports font-lock, imenu and mode-compile.  In the
;; hairy version font-lock is on, but you should activate imenu
;; yourself (note that mode-compile is not standard yet).  Well, you
;; can use imenu from keyboard anyway (M-x imenu), but it is better
;; to bind it like that:
Karl Heuer's avatar
Karl Heuer committed
56 57 58

;; (define-key global-map [M-S-down-mouse-3] 'imenu)

59 60 61 62 63 64 65
;;; Font lock bugs as of v4.32:

;; The following kinds of Perl code erroneously start strings:
;; \$`  \$'  \$"
;; $opt::s  $opt_s  $opt{s}  (s => ...)  /\s+.../
;; likewise with m, tr, y, q, qX instead of s

Karl Heuer's avatar
Karl Heuer committed
66
;;; Code:
67

68 69 70
(defvar vc-rcs-header)
(defvar vc-sccs-header)

Dave Love's avatar
Dave Love committed
71
(eval-when-compile
72 73 74 75 76 77 78
      (condition-case nil
	  (require 'custom)
	(error nil))
      (condition-case nil
	  (require 'man)
	(error nil))
      (defvar cperl-can-font-lock
79
	(or (featurep 'xemacs)
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
	    (and (boundp 'emacs-major-version)
		 (or window-system
		     (> emacs-major-version 20)))))
      (if cperl-can-font-lock
	  (require 'font-lock))
      (defvar msb-menu-cond)
      (defvar gud-perldb-history)
      (defvar font-lock-background-mode) ; not in Emacs
      (defvar font-lock-display-type)	; ditto
      (defvar paren-backwards-message)	; Not in newer XEmacs?
      (or (fboundp 'defgroup)
	  (defmacro defgroup (name val doc &rest arr)
	    nil))
      (or (fboundp 'custom-declare-variable)
	  (defmacro defcustom (name val doc &rest arr)
95
	    `(defvar ,name ,val ,doc)))
96 97 98 99 100 101 102
      (or (and (fboundp 'custom-declare-variable)
	       (string< "19.31" emacs-version))	;  Checked with 19.30: defface does not work
	  (defmacro defface (&rest arr)
	    nil))
      ;; Avoid warning (tmp definitions)
      (or (fboundp 'x-color-defined-p)
	  (defmacro x-color-defined-p (col)
103
	    (cond ((fboundp 'color-defined-p) `(color-defined-p ,col))
104
		  ;; XEmacs >= 19.12
105
		  ((fboundp 'valid-color-name-p) `(valid-color-name-p ,col))
106
		  ;; XEmacs 19.11
107
		  ((fboundp 'x-valid-color-name-p) `(x-valid-color-name-p ,col))
108 109 110
		  (t '(error "Cannot implement color-defined-p")))))
      (defmacro cperl-is-face (arg)	; Takes quoted arg
	(cond ((fboundp 'find-face)
111
	       `(find-face ,arg))
112 113 114
	      (;;(and (fboundp 'face-list)
	       ;;	(face-list))
	       (fboundp 'face-list)
115 116
	       `(member ,arg (and (fboundp 'face-list)
                                  (face-list))))
117
	      (t
118
	       `(boundp ,arg))))
119 120
      (defmacro cperl-make-face (arg descr) ; Takes unquoted arg
	(cond ((fboundp 'make-face)
121
	       `(make-face (quote ,arg)))
122
	      (t
123
	       `(defvar ,arg (quote ,arg) ,descr))))
124
      (defmacro cperl-force-face (arg descr) ; Takes unquoted arg
125 126 127 128 129
	`(progn
	     (or (cperl-is-face (quote ,arg))
		 (cperl-make-face ,arg ,descr))
	     (or (boundp (quote ,arg)) ; We use unquoted variants too
		 (defvar ,arg (quote ,arg) ,descr))))
130
      (if (featurep 'xemacs)
131
	  (defmacro cperl-etags-snarf-tag (file line)
132 133 134
	    `(progn
               (beginning-of-line 2)
               (list ,file ,line)))
135
	(defmacro cperl-etags-snarf-tag (file line)
136
	  `(etags-snarf-tag)))
137
      (if (featurep 'xemacs)
138
	  (defmacro cperl-etags-goto-tag-location (elt)
139 140 141 142 143 144 145
	    ;;(progn
            ;; (switch-to-buffer (get-file-buffer (elt ,elt 0)))
            ;; (set-buffer (get-file-buffer (elt ,elt 0)))
            ;; Probably will not work due to some save-excursion???
            ;; Or save-file-position?
            ;; (message "Did I get to line %s?" (elt ,elt 1))
            `(goto-line (string-to-int (elt ,elt 1))))
146 147
	;;)
	(defmacro cperl-etags-goto-tag-location (elt)
148
	  `(etags-goto-tag-location ,elt))))
149

150
(defvar cperl-can-font-lock
151
  (or (featurep 'xemacs)
152 153 154 155
      (and (boundp 'emacs-major-version)
	   (or window-system
	       (> emacs-major-version 20)))))

156 157 158 159 160 161 162 163 164 165
(defun cperl-choose-color (&rest list)
  (let (answer)
    (while list
      (or answer
	  (if (or (x-color-defined-p (car list))
		  (null (cdr list)))
	      (setq answer (car list))))
      (setq list (cdr list)))
    answer))

166 167 168
(defgroup cperl nil
  "Major mode for editing Perl code."
  :prefix "cperl-"
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
  :group 'languages
  :version "20.3")

(defgroup cperl-indentation-details nil
  "Indentation."
  :prefix "cperl-"
  :group 'cperl)

(defgroup cperl-affected-by-hairy nil
  "Variables affected by `cperl-hairy'."
  :prefix "cperl-"
  :group 'cperl)

(defgroup cperl-autoinsert-details nil
  "Auto-insert tuneup."
  :prefix "cperl-"
  :group 'cperl)

(defgroup cperl-faces nil
  "Fontification colors."
189
  :link '(custom-group-link :tag "Font Lock Faces group" font-lock-faces)
190 191 192 193 194 195 196 197 198 199 200 201
  :prefix "cperl-"
  :group 'cperl)

(defgroup cperl-speed nil
  "Speed vs. validity tuneup."
  :prefix "cperl-"
  :group 'cperl)

(defgroup cperl-help-system nil
  "Help system tuneup."
  :prefix "cperl-"
  :group 'cperl)
202

Karl Heuer's avatar
Karl Heuer committed
203

204
(defcustom cperl-extra-newline-before-brace nil
205
  "Non-nil means that if, elsif, while, until, else, for, foreach
Karl Heuer's avatar
Karl Heuer committed
206 207 208 209 210 211 212 213 214
and do constructs look like:

	if ()
	{
	}

instead of:

	if () {
215
	}"
216
  :type 'boolean
217 218
  :group 'cperl-autoinsert-details)

219
(defcustom cperl-extra-newline-before-brace-multiline
220
  cperl-extra-newline-before-brace
221
  "Non-nil means the same as `cperl-extra-newline-before-brace', but
222 223 224
for constructs with multiline if/unless/while/until/for/foreach condition."
  :type 'boolean
  :group 'cperl-autoinsert-details)
225 226

(defcustom cperl-indent-level 2
227
  "Indentation of CPerl statements with respect to containing block."
228
  :type 'integer
229
  :group 'cperl-indentation-details)
230

231
;; Is is not unusual to put both things like perl-indent-level and
232 233
;; cperl-indent-level in the local variable section of a file. If only
;; one of perl-mode and cperl-mode is in use, a warning will be issued
234
;; about the variable. Autoload these here, so that no warning is
235 236
;; issued when using either perl-mode or cperl-mode.
;;;###autoload(put 'cperl-indent-level 'safe-local-variable 'integerp)
237 238 239 240 241 242
;;;###autoload(put 'cperl-brace-offset 'safe-local-variable 'integerp)
;;;###autoload(put 'cperl-continued-brace-offset 'safe-local-variable 'integerp)
;;;###autoload(put 'cperl-label-offset 'safe-local-variable 'integerp)
;;;###autoload(put 'cperl-continued-statement-offset 'safe-local-variable 'integerp)
;;;###autoload(put 'cperl-extra-newline-before-brace 'safe-local-variable 'booleanp)
;;;###autoload(put 'cperl-merge-trailing-else 'safe-local-variable 'booleanp)
Karl Heuer's avatar
Karl Heuer committed
243

244
(defcustom cperl-lineup-step nil
245
  "`cperl-lineup' will always lineup at multiple of this number.
246
If nil, the value of `cperl-indent-level' will be used."
247
  :type '(choice (const nil) integer)
248 249
  :group 'cperl-indentation-details)

250
(defcustom cperl-brace-imaginary-offset 0
251
  "Imagined indentation of a Perl open brace that actually follows a statement.
Karl Heuer's avatar
Karl Heuer committed
252
An open brace following other text is treated as if it were this far
253 254
to the right of the start of its line."
  :type 'integer
255
  :group 'cperl-indentation-details)
256 257

(defcustom cperl-brace-offset 0
258
  "Extra indentation for braces, compared with other text in same context."
259
  :type 'integer
260
  :group 'cperl-indentation-details)
261
(defcustom cperl-label-offset -2
262
  "Offset of CPerl label lines relative to usual indentation."
263
  :type 'integer
264
  :group 'cperl-indentation-details)
265
(defcustom cperl-min-label-indent 1
266
  "Minimal offset of CPerl label lines."
267
  :type 'integer
268
  :group 'cperl-indentation-details)
269
(defcustom cperl-continued-statement-offset 2
270
  "Extra indent for lines not starting new statements."
271
  :type 'integer
272
  :group 'cperl-indentation-details)
273
(defcustom cperl-continued-brace-offset 0
274
  "Extra indent for substatements that start with open-braces.
275 276
This is in addition to cperl-continued-statement-offset."
  :type 'integer
277
  :group 'cperl-indentation-details)
278
(defcustom cperl-close-paren-offset -1
279
  "Extra indent for substatements that start with close-parenthesis."
280
  :type 'integer
281
  :group 'cperl-indentation-details)
282

283
(defcustom cperl-indent-wrt-brace t
284
  "Non-nil means indent statements in if/etc block relative brace, not if/etc.
285
Versions 5.2 ... 5.20 behaved as if this were nil."
286 287 288
  :type 'boolean
  :group 'cperl-indentation-details)

289
(defcustom cperl-auto-newline nil
290
  "Non-nil means automatically newline before and after braces,
Karl Heuer's avatar
Karl Heuer committed
291 292
and after colons and semicolons, inserted in CPerl code.  The following
\\[cperl-electric-backspace] will remove the inserted whitespace.
293
Insertion after colons requires both this variable and
294 295
`cperl-auto-newline-after-colon' set."
  :type 'boolean
296
  :group 'cperl-autoinsert-details)
Karl Heuer's avatar
Karl Heuer committed
297

Stefan Monnier's avatar
Stefan Monnier committed
298
(defcustom cperl-autoindent-on-semi nil
299
  "Non-nil means automatically indent after insertion of (semi)colon.
Stefan Monnier's avatar
Stefan Monnier committed
300 301 302 303
Active if `cperl-auto-newline' is false."
  :type 'boolean
  :group 'cperl-autoinsert-details)

304
(defcustom cperl-auto-newline-after-colon nil
305
  "Non-nil means automatically newline even after colons.
306 307
Subject to `cperl-auto-newline' setting."
  :type 'boolean
308
  :group 'cperl-autoinsert-details)
Karl Heuer's avatar
Karl Heuer committed
309

310
(defcustom cperl-tab-always-indent t
311
  "Non-nil means TAB in CPerl mode should always reindent the current line,
312 313
regardless of where in the line point is when the TAB command is used."
  :type 'boolean
314
  :group 'cperl-indentation-details)
Karl Heuer's avatar
Karl Heuer committed
315

316
(defcustom cperl-font-lock nil
317
  "Non-nil (and non-null) means CPerl buffers will use `font-lock-mode'.
318
Can be overwritten by `cperl-hairy' if nil."
319 320
  :type '(choice (const null) boolean)
  :group 'cperl-affected-by-hairy)
Karl Heuer's avatar
Karl Heuer committed
321

322
(defcustom cperl-electric-lbrace-space nil
323
  "Non-nil (and non-null) means { after $ should be preceded by ` '.
324
Can be overwritten by `cperl-hairy' if nil."
325 326
  :type '(choice (const null) boolean)
  :group 'cperl-affected-by-hairy)
Karl Heuer's avatar
Karl Heuer committed
327

328
(defcustom cperl-electric-parens-string "({[]})<"
329
  "String of parentheses that should be electric in CPerl.
330 331
Closing ones are electric only if the region is highlighted."
  :type 'string
332
  :group 'cperl-affected-by-hairy)
Karl Heuer's avatar
Karl Heuer committed
333

334
(defcustom cperl-electric-parens nil
335
  "Non-nil (and non-null) means parentheses should be electric in CPerl.
336
Can be overwritten by `cperl-hairy' if nil."
337 338 339 340 341
  :type '(choice (const null) boolean)
  :group 'cperl-affected-by-hairy)

(defvar zmacs-regions)			; Avoid warning

342
(defcustom cperl-electric-parens-mark
Karl Heuer's avatar
Karl Heuer committed
343 344 345 346 347
  (and window-system
       (or (and (boundp 'transient-mark-mode) ; For Emacs
		transient-mark-mode)
	   (and (boundp 'zmacs-regions) ; For XEmacs
		zmacs-regions)))
348
  "Not-nil means that electric parens look for active mark.
349 350
Default is yes if there is visual feedback on mark."
  :type 'boolean
351
  :group 'cperl-autoinsert-details)
Karl Heuer's avatar
Karl Heuer committed
352

353
(defcustom cperl-electric-linefeed nil
354
  "If true, LFD should be hairy in CPerl, otherwise C-c LFD is hairy.
Karl Heuer's avatar
Karl Heuer committed
355
In any case these two mean plain and hairy linefeeds together.
356
Can be overwritten by `cperl-hairy' if nil."
357 358
  :type '(choice (const null) boolean)
  :group 'cperl-affected-by-hairy)
Karl Heuer's avatar
Karl Heuer committed
359

360
(defcustom cperl-electric-keywords nil
361
  "Not-nil (and non-null) means keywords are electric in CPerl.
362 363 364 365 366 367 368 369 370
Can be overwritten by `cperl-hairy' if nil.

Uses `abbrev-mode' to do the expansion.  If you want to use your
own abbrevs in cperl-mode, but do not want keywords to be
electric, you must redefine `cperl-mode-abbrev-table': do
\\[edit-abbrevs], search for `cperl-mode-abbrev-table', and, in
that paragraph, delete the words that appear at the ends of lines and
that begin with \"cperl-electric\".
"
371 372
  :type '(choice (const null) boolean)
  :group 'cperl-affected-by-hairy)
373

Stefan Monnier's avatar
Stefan Monnier committed
374
(defcustom cperl-electric-backspace-untabify t
375
  "Not-nil means electric-backspace will untabify in CPerl."
Stefan Monnier's avatar
Stefan Monnier committed
376 377 378
  :type 'boolean
  :group 'cperl-autoinsert-details)

379
(defcustom cperl-hairy nil
380
  "Not-nil means most of the bells and whistles are enabled in CPerl.
381
Affects: `cperl-font-lock', `cperl-electric-lbrace-space',
382 383 384
`cperl-electric-parens', `cperl-electric-linefeed', `cperl-electric-keywords',
`cperl-info-on-command-no-prompt', `cperl-clobber-lisp-bindings',
`cperl-lazy-help-time'."
385
  :type 'boolean
386
  :group 'cperl-affected-by-hairy)
387 388

(defcustom cperl-comment-column 32
389
  "Column to put comments in CPerl (use \\[cperl-indent] to lineup with code)."
390
  :type 'integer
391
  :group 'cperl-indentation-details)
392

393
(defcustom cperl-indent-comment-at-column-0 nil
394
  "Non-nil means that comment started at column 0 should be indentable."
395 396
  :type 'boolean
  :group 'cperl-indentation-details)
397

398
(defcustom cperl-vc-sccs-header '("($sccs) = ('%W\ %' =~ /(\\d+(\\.\\d+)+)/) ;")
399
  "Special version of `vc-sccs-header' that is used in CPerl mode buffers."
400 401 402
  :type '(repeat string)
  :group 'cperl)

403
(defcustom cperl-vc-rcs-header '("($rcs) = (' $Id\ $ ' =~ /(\\d+(\\.\\d+)+)/);")
404
  "Special version of `vc-rcs-header' that is used in CPerl mode buffers."
405
  :type '(repeat string)
406 407 408 409 410 411
     :group 'cperl)

;; This became obsolete...
(defvar cperl-vc-header-alist nil)
(make-obsolete-variable
 'cperl-vc-header-alist
412 413
 "use cperl-vc-rcs-header or cperl-vc-sccs-header instead."
 "22.1")
414

Glenn Morris's avatar
Glenn Morris committed
415 416 417 418 419 420
;; (defcustom cperl-clobber-mode-lists
;;   (not
;;    (and
;;     (boundp 'interpreter-mode-alist)
;;     (assoc "miniperl" interpreter-mode-alist)
;;     (assoc "\\.\\([pP][Llm]\\|al\\)$" auto-mode-alist)))
421
;;   "Whether to install us into `interpreter-' and `extension' mode lists."
Glenn Morris's avatar
Glenn Morris committed
422 423
;;   :type 'boolean
;;   :group 'cperl)
424

425
(defcustom cperl-info-on-command-no-prompt nil
426
  "Not-nil (and non-null) means not to prompt on C-h f.
427
The opposite behavior is always available if prefixed with C-c.
428
Can be overwritten by `cperl-hairy' if nil."
429 430 431 432
  :type '(choice (const null) boolean)
  :group 'cperl-affected-by-hairy)

(defcustom cperl-clobber-lisp-bindings nil
433
  "Not-nil (and non-null) means not overwrite C-h f.
434 435 436 437
The function is available on \\[cperl-info-on-command], \\[cperl-get-help].
Can be overwritten by `cperl-hairy' if nil."
  :type '(choice (const null) boolean)
  :group 'cperl-affected-by-hairy)
Karl Heuer's avatar
Karl Heuer committed
438

439
(defcustom cperl-lazy-help-time nil
440
  "Not-nil (and non-null) means to show lazy help after given idle time.
441
Can be overwritten by `cperl-hairy' to be 5 sec if nil."
442
  :type '(choice (const null) (const nil) integer)
443
  :group 'cperl-affected-by-hairy)
Karl Heuer's avatar
Karl Heuer committed
444

445
(defcustom cperl-pod-face 'font-lock-comment-face
446
  "Face for POD highlighting."
447
  :type 'face
448
  :group 'cperl-faces)
Karl Heuer's avatar
Karl Heuer committed
449

450
(defcustom cperl-pod-head-face 'font-lock-variable-name-face
451
  "Face for POD highlighting.
452 453
Font for POD headers."
  :type 'face
454
  :group 'cperl-faces)
Karl Heuer's avatar
Karl Heuer committed
455

456
(defcustom cperl-here-face 'font-lock-string-face
457
  "Face for here-docs highlighting."
458
  :type 'face
459
  :group 'cperl-faces)
Karl Heuer's avatar
Karl Heuer committed
460

461
;;; Some double-evaluation happened with font-locks...  Needed with 21.2...
462
(defvar cperl-singly-quote-face (featurep 'xemacs))
463

464
(defcustom cperl-invalid-face 'underline
465
  "Face for highlighting trailing whitespace."
Dave Love's avatar
Dave Love committed
466
  :type 'face
467
  :version "21.1"
468 469
  :group 'cperl-faces)

470
(defcustom cperl-pod-here-fontify '(featurep 'font-lock)
471
  "Not-nil after evaluation means to highlight POD and here-docs sections."
472
  :type 'boolean
473
  :group 'cperl-faces)
Karl Heuer's avatar
Karl Heuer committed
474

475
(defcustom cperl-fontify-m-as-s t
476
  "Not-nil means highlight 1arg regular expressions operators same as 2arg."
477 478 479
  :type 'boolean
  :group 'cperl-faces)

Stefan Monnier's avatar
Stefan Monnier committed
480
(defcustom cperl-highlight-variables-indiscriminately nil
481
  "Non-nil means perform additional highlighting on variables.
Stefan Monnier's avatar
Stefan Monnier committed
482 483 484
Currently only changes how scalar variables are highlighted.
Note that that variable is only read at initialization time for
the variable `cperl-font-lock-keywords-2', so changing it after you've
Richard M. Stallman's avatar
Richard M. Stallman committed
485
entered CPerl mode the first time will have no effect."
Stefan Monnier's avatar
Stefan Monnier committed
486 487 488
  :type 'boolean
  :group 'cperl)

489
(defcustom cperl-pod-here-scan t
490
  "Not-nil means look for POD and here-docs sections during startup.
491 492
You can always make lookup from menu or using \\[cperl-find-pods-heres]."
  :type 'boolean
493
  :group 'cperl-speed)
Karl Heuer's avatar
Karl Heuer committed
494

Stefan Monnier's avatar
Stefan Monnier committed
495
(defcustom cperl-regexp-scan t
496
  "Not-nil means make marking of regular expression more thorough.
497 498 499 500 501
Effective only with `cperl-pod-here-scan'."
  :type 'boolean
  :group 'cperl-speed)

(defcustom cperl-hook-after-change t
502
  "Not-nil means install hook to know which regions of buffer are changed.
503 504
May significantly speed up delayed fontification.  Changes take effect
after reload."
Stefan Monnier's avatar
Stefan Monnier committed
505 506 507
  :type 'boolean
  :group 'cperl-speed)

508
(defcustom cperl-imenu-addback nil
509
  "Not-nil means add backreferences to generated `imenu's.
510
May require patched `imenu' and `imenu-go'.  Obsolete."
511
  :type 'boolean
512
  :group 'cperl-help-system)
Karl Heuer's avatar
Karl Heuer committed
513

514
(defcustom cperl-max-help-size 66
515
  "Non-nil means shrink-wrapping of info-buffer allowed up to these percents."
516
  :type '(choice integer (const nil))
517
  :group 'cperl-help-system)
Karl Heuer's avatar
Karl Heuer committed
518

519
(defcustom cperl-shrink-wrap-info-frame t
520
  "Non-nil means shrink-wrapping of info-buffer-frame allowed."
521
  :type 'boolean
522
  :group 'cperl-help-system)
Karl Heuer's avatar
Karl Heuer committed
523

524
(defcustom cperl-info-page "perl"
525
  "Name of the info page containing perl docs.
526 527
Older version of this page was called `perl5', newer `perl'."
  :type 'string
528
  :group 'cperl-help-system)
Karl Heuer's avatar
Karl Heuer committed
529

530
(defcustom cperl-use-syntax-table-text-property
Karl Heuer's avatar
Karl Heuer committed
531
  (boundp 'parse-sexp-lookup-properties)
532
  "Non-nil means CPerl sets up and uses `syntax-table' text property."
533
  :type 'boolean
534
  :group 'cperl-speed)
Karl Heuer's avatar
Karl Heuer committed
535

536
(defcustom cperl-use-syntax-table-text-property-for-tags
Karl Heuer's avatar
Karl Heuer committed
537
  cperl-use-syntax-table-text-property
538
  "Non-nil means: set up and use `syntax-table' text property generating TAGS."
539
  :type 'boolean
540
  :group 'cperl-speed)
541 542

(defcustom cperl-scan-files-regexp "\\.\\([pP][Llm]\\|xs\\)$"
543
  "Regexp to match files to scan when generating TAGS."
544 545 546
  :type 'regexp
  :group 'cperl)

547 548
(defcustom cperl-noscan-files-regexp
  "/\\(\\.\\.?\\|SCCS\\|RCS\\|CVS\\|blib\\)$"
549
  "Regexp to match files/dirs to skip when generating TAGS."
550 551 552 553
  :type 'regexp
  :group 'cperl)

(defcustom cperl-regexp-indent-step nil
554
  "Indentation used when beautifying regexps.
555
If nil, the value of `cperl-indent-level' will be used."
556
  :type '(choice integer (const nil))
557
  :group 'cperl-indentation-details)
558 559

(defcustom cperl-indent-left-aligned-comments t
560
  "Non-nil means that the comment starting in leftmost column should indent."
561
  :type 'boolean
562
  :group 'cperl-indentation-details)
563

564
(defcustom cperl-under-as-char nil
565
  "Non-nil means that the _ (underline) should be treated as word char."
566 567
  :type 'boolean
  :group 'cperl)
568
(make-obsolete-variable 'cperl-under-as-char 'superword-mode "24.4")
Karl Heuer's avatar
Karl Heuer committed
569

570
(defcustom cperl-extra-perl-args ""
571
  "Extra arguments to use when starting Perl.
572 573 574 575 576
Currently used with `cperl-check-syntax' only."
  :type 'string
  :group 'cperl)

(defcustom cperl-message-electric-keyword t
577
  "Non-nil means that the `cperl-electric-keyword' prints a help message."
578 579 580 581
  :type 'boolean
  :group 'cperl-help-system)

(defcustom cperl-indent-region-fix-constructs 1
582
  "Amount of space to insert between `}' and `else' or `elsif'
583 584 585 586 587 588
in `cperl-indent-region'.  Set to nil to leave as is.  Values other
than 1 and nil will probably not work."
  :type '(choice (const nil) (const 1))
  :group 'cperl-indentation-details)

(defcustom cperl-break-one-line-blocks-when-indent t
589
  "Non-nil means that one-line if/unless/while/until/for/foreach BLOCKs
590
need to be reformatted into multiline ones when indenting a region."
591 592 593 594
  :type 'boolean
  :group 'cperl-indentation-details)

(defcustom cperl-fix-hanging-brace-when-indent t
595
  "Non-nil means that BLOCK-end `}' may be put on a separate line
596
when indenting a region.
597 598 599 600 601
Braces followed by else/elsif/while/until are excepted."
  :type 'boolean
  :group 'cperl-indentation-details)

(defcustom cperl-merge-trailing-else t
602
  "Non-nil means that BLOCK-end `}' followed by else/elsif/continue
603 604 605 606
may be merged to be on the same line when indenting a region."
  :type 'boolean
  :group 'cperl-indentation-details)

Stefan Monnier's avatar
Stefan Monnier committed
607
(defcustom cperl-indent-parens-as-block nil
608
  "Non-nil means that non-block ()-, {}- and []-groups are indented as blocks,
Stefan Monnier's avatar
Stefan Monnier committed
609 610 611 612 613
but for trailing \",\" inside the group, which won't increase indentation.
One should tune up `cperl-close-paren-offset' as well."
  :type 'boolean
  :group 'cperl-indentation-details)

614
(defcustom cperl-syntaxify-by-font-lock
615
  (and cperl-can-font-lock
616
       (boundp 'parse-sexp-lookup-properties))
617
  "Non-nil means that CPerl uses the `font-lock' routines for syntaxification."
618 619 620 621 622
  :type '(choice (const message) boolean)
  :group 'cperl-speed)

(defcustom cperl-syntaxify-unwind
  t
623
  "Non-nil means that CPerl unwinds to a start of a long construction
624
when syntaxifying a chunk of buffer."
625 626 627
  :type 'boolean
  :group 'cperl-speed)

628 629
(defcustom cperl-syntaxify-for-menu
  t
630
  "Non-nil means that CPerl syntaxifies up to the point before showing menu.
631 632 633 634
This way enabling/disabling of menu items is more correct."
  :type 'boolean
  :group 'cperl-speed)

635 636 637 638 639
(defcustom cperl-ps-print-face-properties
  '((font-lock-keyword-face		nil nil		bold shadow)
    (font-lock-variable-name-face	nil nil		bold)
    (font-lock-function-name-face	nil nil		bold italic box)
    (font-lock-constant-face		nil "LightGray"	bold)
640
    (cperl-array-face			nil "LightGray"	bold underline)
641
    (cperl-hash-face			nil "LightGray"	bold italic underline)
642 643
    (font-lock-comment-face		nil "LightGray"	italic)
    (font-lock-string-face		nil nil		italic underline)
644
    (cperl-nonoverridable-face		nil nil		italic underline)
645
    (font-lock-type-face		nil nil		underline)
646
    (font-lock-warning-face		nil "LightGray"	bold italic box)
647 648
    (underline				nil "LightGray"	strikeout))
  "List given as an argument to `ps-extend-face-list' in `cperl-ps-print'."
649
  :type '(repeat (cons symbol
650 651 652 653 654
		       (cons (choice (const nil) string)
			     (cons (choice (const nil) string)
				   (repeat symbol)))))
  :group 'cperl-faces)

655 656 657 658 659
(defvar cperl-dark-background
  (cperl-choose-color "navy" "os2blue" "darkgreen"))
(defvar cperl-dark-foreground
  (cperl-choose-color "orchid1" "orange"))

660
(defface cperl-nonoverridable-face
661 662 663 664 665 666 667 668 669
  `((((class grayscale) (background light))
     (:background "Gray90" :slant italic :underline t))
    (((class grayscale) (background dark))
     (:foreground "Gray80" :slant italic :underline t :weight bold))
    (((class color) (background light))
     (:foreground "chartreuse3"))
    (((class color) (background dark))
     (:foreground ,cperl-dark-foreground))
    (t (:weight bold :underline t)))
670
  "Font Lock mode face used non-overridable keywords and modifiers of regexps."
671 672
  :group 'cperl-faces)

673
(defface cperl-array-face
674 675 676 677 678 679 680 681 682 683 684 685
  `((((class grayscale) (background light))
     (:background "Gray90" :weight bold))
    (((class grayscale) (background dark))
     (:foreground "Gray80" :weight bold))
    (((class color) (background light))
     (:foreground "Blue" :background "lightyellow2" :weight bold))
    (((class color) (background dark))
     (:foreground "yellow" :background ,cperl-dark-background :weight bold))
    (t (:weight bold)))
  "Font Lock mode face used to highlight array names."
  :group 'cperl-faces)

686
(defface cperl-hash-face
687 688 689 690 691 692 693 694 695 696 697
  `((((class grayscale) (background light))
     (:background "Gray90" :weight bold :slant italic))
    (((class grayscale) (background dark))
     (:foreground "Gray80" :weight bold :slant italic))
    (((class color) (background light))
     (:foreground "Red" :background "lightyellow2" :weight bold :slant italic))
    (((class color) (background dark))
     (:foreground "Red" :background ,cperl-dark-background :weight bold :slant italic))
    (t (:weight bold :slant italic)))
  "Font Lock mode face used to highlight hash names."
  :group 'cperl-faces)
698

Karl Heuer's avatar
Karl Heuer committed
699 700 701 702 703


;;; Short extra-docs.

(defvar cperl-tips 'please-ignore-this-line
704
  "Get maybe newer version of this package from
705
  http://ilyaz.org/software/emacs
706 707
Subdirectory `cperl-mode' may contain yet newer development releases and/or
patches to related files.
Karl Heuer's avatar
Karl Heuer committed
708

709 710
For best results apply to an older Emacs the patches from
  ftp://ftp.math.ohio-state.edu/pub/users/ilya/cperl-mode/patches
711
\(this upgrades syntax-parsing abilities of Emacsen v19.34 and
712
v20.2 up to the level of Emacs v20.3 - a must for a good Perl
713
mode.)  As of beginning of 2003, XEmacs may provide a similar ability.
714

Karl Heuer's avatar
Karl Heuer committed
715 716 717
Get support packages choose-color.el (or font-lock-extra.el before
19.30), imenu-go.el from the same place.  \(Look for other files there
too... ;-).  Get a patch for imenu.el in 19.29.  Note that for 19.30 and
718
later you should use choose-color.el *instead* of font-lock-extra.el
Karl Heuer's avatar
Karl Heuer committed
719 720 721 722 723
\(and you will not get smart highlighting in C :-().

Note that to enable Compile choices in the menu you need to install
mode-compile.el.

Stefan Monnier's avatar
Stefan Monnier committed
724 725 726
If your Emacs does not default to `cperl-mode' on Perl files, and you
want it to: put the following into your .emacs file:

727
  (defalias \\='perl-mode \\='cperl-mode)
Stefan Monnier's avatar
Stefan Monnier committed
728

729
Get perl5-info from
730 731 732
  $CPAN/doc/manual/info/perl5-old/perl5-info.tar.gz
Also, one can generate a newer documentation running `pod2texi' converter
  $CPAN/doc/manual/info/perl5/pod2texi-0.1.tar.gz
Karl Heuer's avatar
Karl Heuer committed
733 734

If you use imenu-go, run imenu on perl5-info buffer (you can do it
735 736
from Perl menu).  If many files are related, generate TAGS files from
Tools/Tags submenu in Perl menu.
Karl Heuer's avatar
Karl Heuer committed
737 738

If some class structure is too complicated, use Tools/Hierarchy-view
739
from Perl menu, or hierarchic view of imenu.  The second one uses the
Karl Heuer's avatar
Karl Heuer committed
740
current buffer only, the first one requires generation of TAGS from
741 742 743 744 745 746 747 748 749
Perl/Tools/Tags menu beforehand.

Run Perl/Tools/Insert-spaces-if-needed to fix your lazy typing.

Switch auto-help on/off with Perl/Tools/Auto-help.

Though with contemporary Emaxen CPerl mode should maintain the correct
parsing of Perl even when editing, sometimes it may be lost.  Fix this by

750
  \\[normal-mode]
Karl Heuer's avatar
Karl Heuer committed
751

752
In cases of more severe confusion sometimes it is helpful to do
Karl Heuer's avatar
Karl Heuer committed
753

754 755
  \\[load-library] cperl-mode RET
  \\[normal-mode]
Karl Heuer's avatar
Karl Heuer committed
756

757 758
Before reporting (non-)problems look in the problem section of online
micro-docs on what I know about CPerl problems.")
Karl Heuer's avatar
Karl Heuer committed
759 760

(defvar cperl-problems 'please-ignore-this-line
Richard M. Stallman's avatar
Richard M. Stallman committed
761 762
  "Description of problems in CPerl mode.
Some faces will not be shown on some versions of Emacs unless you
763
install choose-color.el, available from
764
  http://ilyaz.org/software/emacs
765

Stefan Monnier's avatar
Stefan Monnier committed
766
`fill-paragraph' on a comment may leave the point behind the
767 768 769 770 771 772 773 774 775
paragraph.  It also triggers a bug in some versions of Emacs (CPerl tries
to detect it and bulk out).

See documentation of a variable `cperl-problems-old-emaxen' for the
problems which disappear if you upgrade Emacs to a reasonably new
version (20.3 for Emacs, and those of 2004 for XEmacs).")

(defvar cperl-problems-old-emaxen 'please-ignore-this-line
  "Description of problems in CPerl mode specific for older Emacs versions.
Stefan Monnier's avatar
Stefan Monnier committed
776

777
Emacs had a _very_ restricted syntax parsing engine until version
778
20.1.  Most problems below are corrected starting from this version of
779
Emacs, and all of them should be fixed in version 20.3.  (Or apply
780 781
patches to Emacs 19.33/34 - see tips.)  XEmacs was very backward in
this respect (until 2003).
782

Stefan Monnier's avatar
Stefan Monnier committed
783 784 785 786 787
Note that even with newer Emacsen in some very rare cases the details
of interaction of `font-lock' and syntaxification may be not cleaned
up yet.  You may get slightly different colors basing on the order of
fontification and syntaxification.  Say, the initial faces is correct,
but editing the buffer breaks this.
Karl Heuer's avatar
Karl Heuer committed
788

789 790 791 792 793 794
Even with older Emacsen CPerl mode tries to corrects some Emacs
misunderstandings, however, for efficiency reasons the degree of
correction is different for different operations.  The partially
corrected problems are: POD sections, here-documents, regexps.  The
operations are: highlighting, indentation, electric keywords, electric
braces.
Karl Heuer's avatar
Karl Heuer committed
795

796
This may be confusing, since the regexp s#//#/#; may be highlighted
Karl Heuer's avatar
Karl Heuer committed
797
as a comment, but it will be recognized as a regexp by the indentation
798
code.  Or the opposite case, when a POD section is highlighted, but
Karl Heuer's avatar
Karl Heuer committed
799 800 801 802 803
may break the indentation of the following code (though indentation
should work if the balance of delimiters is not broken by POD).

The main trick (to make $ a \"backslash\") makes constructions like
${aaa} look like unbalanced braces.  The only trick I can think of is
804
to insert it as $ {aaa} (valid in perl5, not in perl4).
Karl Heuer's avatar
Karl Heuer committed
805 806

Similar problems arise in regexps, when /(\\s|$)/ should be rewritten
807 808
as /($|\\s)/.  Note that such a transposition is not always possible.

809
The solution is to upgrade your Emacs or patch an older one.  Note
810
that Emacs 20.2 has some bugs related to `syntax-table' text
811 812
properties.  Patches are available on the main CPerl download site,
and on CPAN.
813 814 815

If these bugs cannot be fixed on your machine (say, you have an inferior
environment and cannot recompile), you may still disable all the fancy stuff
816
via `cperl-use-syntax-table-text-property'.")
Karl Heuer's avatar
Karl Heuer committed
817 818

(defvar cperl-praise 'please-ignore-this-line
819
  "Advantages of CPerl mode.
Karl Heuer's avatar
Karl Heuer committed
820 821 822 823

0) It uses the newest `syntax-table' property ;-);

1) It does 99% of Perl syntax correct (as opposed to 80-90% in Perl
824
mode - but the latter number may have improved too in last years) even
825 826 827 828 829
with old Emaxen which do not support `syntax-table' property.

When using `syntax-table' property for syntax assist hints, it should
handle 99.995% of lines correct - or somesuch.  It automatically
updates syntax assist hints when you edit your script.
Karl Heuer's avatar
Karl Heuer committed
830

831
2) It is generally believed to be \"the most user-friendly Emacs
Karl Heuer's avatar
Karl Heuer committed
832 833 834 835 836 837
package\" whatever it may mean (I doubt that the people who say similar
things tried _all_ the rest of Emacs ;-), but this was not a lonely
voice);

3) Everything is customizable, one-by-one or in a big sweep;

Glenn Morris's avatar
Glenn Morris committed
838
4) It has many easily-accessible \"tools\":
Karl Heuer's avatar
Karl Heuer committed
839 840 841 842
        a) Can run program, check syntax, start debugger;
        b) Can lineup vertically \"middles\" of rows, like `=' in
                a  = b;
                cc = d;
Paul Eggert's avatar
Paul Eggert committed
843
        c) Can insert spaces where this improves readability (in one
Karl Heuer's avatar
Karl Heuer committed
844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861
                interactive sweep over the buffer);
        d) Has support for imenu, including:
                1) Separate unordered list of \"interesting places\";
                2) Separate TOC of POD sections;
                3) Separate list of packages;
                4) Hierarchical view of methods in (sub)packages;
                5) and functions (by the full name - with package);
        e) Has an interface to INFO docs for Perl; The interface is
                very flexible, including shrink-wrapping of
                documentation buffer/frame;
        f) Has a builtin list of one-line explanations for perl constructs.
        g) Can show these explanations if you stay long enough at the
                corresponding place (or on demand);
        h) Has an enhanced fontification (using 3 or 4 additional faces
                comparing to font-lock - basically, different
                namespaces in Perl have different colors);
        i) Can construct TAGS basing on its knowledge of Perl syntax,
                the standard menu has 6 different way to generate
862
                TAGS (if \"by directory\", .xs files - with C-language
Karl Heuer's avatar
Karl Heuer committed
863 864 865 866 867 868 869 870 871 872
                bindings - are included in the scan);
        j) Can build a hierarchical view of classes (via imenu) basing
                on generated TAGS file;
        k) Has electric parentheses, electric newlines, uses Abbrev
                for electric logical constructs
                        while () {}
                with different styles of expansion (context sensitive
                to be not so bothering).  Electric parentheses behave
                \"as they should\" in a presence of a visible region.
        l) Changes msb.el \"on the fly\" to insert a group \"Perl files\";
873 874 875 876
        m) Can convert from
		if (A) { B }
	   to
		B if A;
Karl Heuer's avatar
Karl Heuer committed
877

878
        n) Highlights (by user-choice) either 3-delimiters constructs
Stefan Monnier's avatar
Stefan Monnier committed
879 880 881 882
	   (such as tr/a/b/), or regular expressions and `y/tr';
	o) Highlights trailing whitespace;
	p) Is able to manipulate Perl Regular Expressions to ease
	   conversion to a more readable form.
883 884 885 886 887 888 889
        q) Can ispell POD sections and HERE-DOCs.
	r) Understands comments and character classes inside regular
	   expressions; can find matching () and [] in a regular expression.
	s) Allows indentation of //x-style regular expressions;
	t) Highlights different symbols in regular expressions according
	   to their function; much less problems with backslashitis;
	u) Allows to find regular expressions which contain interpolated parts.
890

Karl Heuer's avatar
Karl Heuer committed
891 892 893 894
5) The indentation engine was very smart, but most of tricks may be
not needed anymore with the support for `syntax-table' property.  Has
progress indicator for indentation (with `imenu' loaded).

895
6) Indent-region improves inline-comments as well; also corrects
896
whitespace *inside* the conditional/loop constructs.
Karl Heuer's avatar
Karl Heuer committed
897 898

7) Fill-paragraph correctly handles multi-line comments;
899 900 901 902

8) Can switch to different indentation styles by one command, and restore
the settings present before the switch.

903
9) When doing indentation of control constructs, may correct
904
line-breaks/spacing between elements of the construct.
905

Paul Eggert's avatar
Paul Eggert committed
906
10) Uses a linear-time algorithm for indentation of regions (on Emaxen with
907 908 909 910
capable syntax engines).

11) Syntax-highlight, indentation, sexp-recognition inside regular expressions.
")
911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930

(defvar cperl-speed 'please-ignore-this-line
  "This is an incomplete compendium of what is available in other parts
of CPerl documentation.  (Please inform me if I skept anything.)

There is a perception that CPerl is slower than alternatives.  This part
of documentation is designed to overcome this misconception.

*By default* CPerl tries to enable the most comfortable settings.
From most points of view, correctly working package is infinitely more
comfortable than a non-correctly working one, thus by default CPerl
prefers correctness over speed.  Below is the guide how to change
settings if your preferences are different.

A)  Speed of loading the file.  When loading file, CPerl may perform a
scan which indicates places which cannot be parsed by primitive Emacs
syntax-parsing routines, and marks them up so that either

    A1) CPerl may work around these deficiencies (for big chunks, mostly
        PODs and HERE-documents), or
Paul Eggert's avatar
Paul Eggert committed
931
    A2) On capable Emaxen CPerl will use improved syntax-handling