]> code.delx.au - gnu-emacs/blob - lisp/eshell/em-pred.el
Convert consecutive FSF copyright years to ranges.
[gnu-emacs] / lisp / eshell / em-pred.el
1 ;;; em-pred.el --- argument predicates and modifiers (ala zsh)
2
3 ;; Copyright (C) 1999-2011 Free Software Foundation, Inc.
4
5 ;; Author: John Wiegley <johnw@gnu.org>
6
7 ;; This file is part of GNU Emacs.
8
9 ;; GNU Emacs is free software: you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
13
14 ;; GNU Emacs is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
18
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
21
22 ;;; Commentary:
23
24 ;; Argument predication is used to affect which members of a list are
25 ;; selected for use as argument. This is most useful with globbing,
26 ;; but can be used on any list argument, to select certain members.
27 ;;
28 ;; Argument modifiers are used to manipulate argument values. For
29 ;; example, sorting lists, upcasing words, substituting characters,
30 ;; etc.
31 ;;
32 ;; Here are some examples of how to use argument predication. Most of
33 ;; the predicates and modifiers are modeled after those provided by
34 ;; zsh.
35 ;;
36 ;; ls -ld *(/) ; list all directories
37 ;; ls -l *(@u'johnw') ; list all symlinks owned by 'johnw'
38 ;; bzip2 -9v **/*(a+30) ; compress everything which hasn't been
39 ;; accessed in 30 days
40 ;; echo *.c(:o:R) ; a reversed, sorted list of C files
41 ;; *(^@:U^u0) ; all non-symlinks not owned by 'root', upcased
42 ;; chmod u-x *(U*) : remove exec bit on all executables owned by user
43 ;;
44 ;; See the zsh docs for more on the syntax ([(zsh.info)Filename
45 ;; Generation]).
46
47 ;;; Code:
48
49 (eval-when-compile (require 'eshell))
50
51 ;;;###autoload
52 (eshell-defgroup eshell-pred nil
53 "This module allows for predicates to be applied to globbing
54 patterns (similar to zsh), in addition to string modifiers which can
55 be applied either to globbing results, variable references, or just
56 ordinary strings."
57 :tag "Value modifiers and predicates"
58 :group 'eshell-module)
59
60 ;;; User Variables:
61
62 (defcustom eshell-pred-load-hook '(eshell-pred-initialize)
63 "A list of functions to run when `eshell-pred' is loaded."
64 :type 'hook
65 :group 'eshell-pred)
66
67 (defcustom eshell-predicate-alist
68 '((?/ . (eshell-pred-file-type ?d)) ; directories
69 (?. . (eshell-pred-file-type ?-)) ; regular files
70 (?s . (eshell-pred-file-type ?s)) ; sockets
71 (?p . (eshell-pred-file-type ?p)) ; named pipes
72 (?@ . (eshell-pred-file-type ?l)) ; symbolic links
73 (?% . (eshell-pred-file-type ?%)) ; allow user to specify (c def.)
74 (?r . (eshell-pred-file-mode 0400)) ; owner-readable
75 (?w . (eshell-pred-file-mode 0200)) ; owner-writable
76 (?x . (eshell-pred-file-mode 0100)) ; owner-executable
77 (?A . (eshell-pred-file-mode 0040)) ; group-readable
78 (?I . (eshell-pred-file-mode 0020)) ; group-writable
79 (?E . (eshell-pred-file-mode 0010)) ; group-executable
80 (?R . (eshell-pred-file-mode 0004)) ; world-readable
81 (?W . (eshell-pred-file-mode 0002)) ; world-writable
82 (?X . (eshell-pred-file-mode 0001)) ; world-executable
83 (?s . (eshell-pred-file-mode 4000)) ; setuid
84 (?S . (eshell-pred-file-mode 2000)) ; setgid
85 (?t . (eshell-pred-file-mode 1000)) ; sticky bit
86 (?U . '(lambda (file) ; owned by effective uid
87 (if (file-exists-p file)
88 (= (nth 2 (file-attributes file)) (user-uid)))))
89 ;;; (?G . '(lambda (file) ; owned by effective gid
90 ;;; (if (file-exists-p file)
91 ;;; (= (nth 2 (file-attributes file)) (user-uid)))))
92 (?* . '(lambda (file)
93 (and (file-regular-p file)
94 (not (file-symlink-p file))
95 (file-executable-p file))))
96 (?l . (eshell-pred-file-links))
97 (?u . (eshell-pred-user-or-group ?u "user" 2 'eshell-user-id))
98 (?g . (eshell-pred-user-or-group ?g "group" 3 'eshell-group-id))
99 (?a . (eshell-pred-file-time ?a "access" 4))
100 (?m . (eshell-pred-file-time ?m "modification" 5))
101 (?c . (eshell-pred-file-time ?c "change" 6))
102 (?L . (eshell-pred-file-size)))
103 "A list of predicates than can be applied to a globbing pattern.
104 The format of each entry is
105
106 (CHAR . PREDICATE-FUNC-SEXP)"
107 :type '(repeat (cons character sexp))
108 :group 'eshell-pred)
109
110 (put 'eshell-predicate-alist 'risky-local-variable t)
111
112 (defcustom eshell-modifier-alist
113 '((?E . '(lambda (lst)
114 (mapcar
115 (function
116 (lambda (str)
117 (eshell-stringify
118 (car (eshell-parse-argument str))))) lst)))
119 (?L . '(lambda (lst)
120 (mapcar 'downcase lst)))
121 (?U . '(lambda (lst)
122 (mapcar 'upcase lst)))
123 (?C . '(lambda (lst)
124 (mapcar 'capitalize lst)))
125 (?h . '(lambda (lst)
126 (mapcar 'file-name-directory lst)))
127 (?i . (eshell-include-members))
128 (?x . (eshell-include-members t))
129 (?r . '(lambda (lst)
130 (mapcar 'file-name-sans-extension lst)))
131 (?e . '(lambda (lst)
132 (mapcar 'file-name-extension lst)))
133 (?t . '(lambda (lst)
134 (mapcar 'file-name-nondirectory lst)))
135 (?q . '(lambda (lst)
136 (mapcar 'eshell-escape-arg lst)))
137 (?u . '(lambda (lst)
138 (eshell-uniqify-list lst)))
139 (?o . '(lambda (lst)
140 (sort lst 'string-lessp)))
141 (?O . '(lambda (lst)
142 (nreverse (sort lst 'string-lessp))))
143 (?j . (eshell-join-members))
144 (?S . (eshell-split-members))
145 (?R . 'reverse)
146 (?g . (progn
147 (forward-char)
148 (if (eq (char-before) ?s)
149 (eshell-pred-substitute t)
150 (error "`g' modifier cannot be used alone"))))
151 (?s . (eshell-pred-substitute)))
152 "A list of modifiers than can be applied to an argument expansion.
153 The format of each entry is
154
155 (CHAR ENTRYWISE-P MODIFIER-FUNC-SEXP)"
156 :type '(repeat (cons character sexp))
157 :group 'eshell-pred)
158
159 (put 'eshell-modifier-alist 'risky-local-variable t)
160
161 (defvar eshell-predicate-help-string
162 "Eshell predicate quick reference:
163
164 - follow symbolic references for predicates after the `-'
165 ^ invert sense of predicates after the `^'
166
167 FILE TYPE:
168 / directories s sockets
169 . regular files p named pipes
170 * executable (files only) @ symbolic links
171
172 %x file type == `x' (as by ls -l; so `c' = char device, etc.)
173
174 PERMISSION BITS (for owner/group/world):
175 r/A/R readable s setuid
176 w/I/W writable S setgid
177 x/E/X executable t sticky bit
178
179 OWNERSHIP:
180 U owned by effective uid
181 u(UID|'user') owned by UID/user
182 g(GID|'group') owned by GID/group
183
184 FILE ATTRIBUTES:
185 l[+-]N +/-/= N links
186 a[Mwhms][+-](N|'FILE') access time +/-/= N mnths/weeks/hours/mins/secs
187 (days if unspecified) if FILE specified,
188 use as comparison basis; so a+'file.c'
189 shows files accessed before file.c was
190 last accessed
191 m[Mwhms][+-](N|'FILE') modification time...
192 c[Mwhms][+-](N|'FILE') change time...
193 L[kmp][+-]N file size +/-/= N Kb/Mb/blocks
194
195 EXAMPLES:
196 *(^@) all non-dot files which are not symlinks
197 .#*(^@) all files which are not symbolic links
198 **/.#*(*) all executable files, searched recursively
199 ***/*~f*(-/) recursively (though not traversing symlinks),
200 find all directories (or symlinks referring to
201 directories) whose names do not begin with f.
202 e*(*Lk+50) executables 50k or larger beginning with 'e'")
203
204 (defvar eshell-modifier-help-string
205 "Eshell modifier quick reference:
206
207 FOR SINGLE ARGUMENTS, or each argument of a list of strings:
208 E evaluate again
209 L lowercase
210 U uppercase
211 C capitalize
212 h dirname
213 t basename
214 e file extension
215 r strip file extension
216 q escape special characters
217
218 S split string at any whitespace character
219 S/PAT/ split string at each occurrence of PAT
220
221 FOR LISTS OF ARGUMENTS:
222 o sort alphabetically
223 O reverse sort alphabetically
224 u uniq list (typically used after :o or :O)
225 R reverse list
226
227 j join list members, separated by a space
228 j/PAT/ join list members, separated by PAT
229 i/PAT/ exclude all members not matching PAT
230 x/PAT/ exclude all members matching PAT
231
232 s/pat/match/ substitute PAT with MATCH
233 g/pat/match/ substitute PAT with MATCH for all occurrences
234
235 EXAMPLES:
236 *.c(:o) sorted list of .c files")
237
238 ;;; Functions:
239
240 (defun eshell-display-predicate-help ()
241 (interactive)
242 (with-electric-help
243 (function
244 (lambda ()
245 (insert eshell-predicate-help-string)))))
246
247 (defun eshell-display-modifier-help ()
248 (interactive)
249 (with-electric-help
250 (function
251 (lambda ()
252 (insert eshell-modifier-help-string)))))
253
254 (defun eshell-pred-initialize ()
255 "Initialize the predicate/modifier code."
256 (add-hook 'eshell-parse-argument-hook
257 'eshell-parse-arg-modifier t t)
258 (define-key eshell-command-map [(meta ?q)] 'eshell-display-predicate-help)
259 (define-key eshell-command-map [(meta ?m)] 'eshell-display-modifier-help))
260
261 (defun eshell-apply-modifiers (lst predicates modifiers)
262 "Apply to LIST a series of PREDICATES and MODIFIERS."
263 (let (stringified)
264 (if (stringp lst)
265 (setq lst (list lst)
266 stringified t))
267 (when (listp lst)
268 (setq lst (eshell-winnow-list lst nil predicates))
269 (while modifiers
270 (setq lst (funcall (car modifiers) lst)
271 modifiers (cdr modifiers)))
272 (if (and stringified
273 (= (length lst) 1))
274 (car lst)
275 lst))))
276
277 (defun eshell-parse-arg-modifier ()
278 "Parse a modifier that has been specified after an argument.
279 This function is specially for adding onto `eshell-parse-argument-hook'."
280 (when (eq (char-after) ?\()
281 (forward-char)
282 (let ((end (eshell-find-delimiter ?\( ?\))))
283 (if (not end)
284 (throw 'eshell-incomplete ?\()
285 (when (eshell-arg-delimiter (1+ end))
286 (save-restriction
287 (narrow-to-region (point) end)
288 (let* ((modifiers (eshell-parse-modifiers))
289 (preds (car modifiers))
290 (mods (cdr modifiers)))
291 (if (or preds mods)
292 ;; has to go at the end, which is only natural since
293 ;; syntactically it can only occur at the end
294 (setq eshell-current-modifiers
295 (append
296 eshell-current-modifiers
297 (list
298 `(lambda (lst)
299 (eshell-apply-modifiers
300 lst (quote ,preds) (quote ,mods)))))))))
301 (goto-char (1+ end))
302 (eshell-finish-arg))))))
303
304 (defun eshell-parse-modifiers ()
305 "Parse value modifiers and predicates at point.
306 If ALLOW-PREDS is non-nil, predicates will be parsed as well.
307 Return a cons cell of the form
308
309 (PRED-FUNC-LIST . MOD-FUNC-LIST)
310
311 NEW-STRING is STRING minus any modifiers. PRED-FUNC-LIST is a list of
312 predicate functions. MOD-FUNC-LIST is a list of result modifier
313 functions. PRED-FUNCS take a filename and return t if the test
314 succeeds; MOD-FUNCS take any string and preform a modification,
315 returning the resultant string."
316 (let (result negate follow preds mods)
317 (condition-case err
318 (while (not (eobp))
319 (let ((char (char-after)))
320 (cond
321 ((eq char ?')
322 (forward-char)
323 (if (looking-at "[^|':]")
324 (let ((func (read (current-buffer))))
325 (if (and func (functionp func))
326 (setq preds (eshell-add-pred-func func preds
327 negate follow))
328 (error "Invalid function predicate '%s'"
329 (eshell-stringify func))))
330 (error "Invalid function predicate")))
331 ((eq char ?^)
332 (forward-char)
333 (setq negate (not negate)))
334 ((eq char ?-)
335 (forward-char)
336 (setq follow (not follow)))
337 ((eq char ?|)
338 (forward-char)
339 (if (looking-at "[^|':]")
340 (let ((func (read (current-buffer))))
341 (if (and func (functionp func))
342 (setq mods
343 (cons `(lambda (lst)
344 (mapcar (function ,func) lst))
345 mods))
346 (error "Invalid function modifier '%s'"
347 (eshell-stringify func))))
348 (error "Invalid function modifier")))
349 ((eq char ?:)
350 (forward-char)
351 (let ((mod (assq (char-after) eshell-modifier-alist)))
352 (if (not mod)
353 (error "Unknown modifier character '%c'" (char-after))
354 (forward-char)
355 (setq mods (cons (eval (cdr mod)) mods)))))
356 (t
357 (let ((pred (assq char eshell-predicate-alist)))
358 (if (not pred)
359 (error "Unknown predicate character '%c'" char)
360 (forward-char)
361 (setq preds
362 (eshell-add-pred-func (eval (cdr pred)) preds
363 negate follow))))))))
364 (end-of-buffer
365 (error "Predicate or modifier ended prematurely")))
366 (cons (nreverse preds) (nreverse mods))))
367
368 (defun eshell-add-pred-func (pred funcs negate follow)
369 "Add the predicate function PRED to FUNCS."
370 (if negate
371 (setq pred `(lambda (file)
372 (not (funcall ,pred file)))))
373 (if follow
374 (setq pred `(lambda (file)
375 (funcall ,pred (file-truename file)))))
376 (cons pred funcs))
377
378 (defun eshell-pred-user-or-group (mod-char mod-type attr-index get-id-func)
379 "Return a predicate to test whether a file match a given user/group id."
380 (let (ugid open close end)
381 (if (looking-at "[0-9]+")
382 (progn
383 (setq ugid (string-to-number (match-string 0)))
384 (goto-char (match-end 0)))
385 (setq open (char-after))
386 (if (setq close (memq open '(?\( ?\[ ?\< ?\{)))
387 (setq close (car (last '(?\) ?\] ?\> ?\})
388 (length close))))
389 (setq close open))
390 (forward-char)
391 (setq end (eshell-find-delimiter open close))
392 (unless end
393 (error "Malformed %s name string for modifier `%c'"
394 mod-type mod-char))
395 (setq ugid
396 (funcall get-id-func (buffer-substring (point) end)))
397 (goto-char (1+ end)))
398 (unless ugid
399 (error "Unknown %s name specified for modifier `%c'"
400 mod-type mod-char))
401 `(lambda (file)
402 (let ((attrs (file-attributes file)))
403 (if attrs
404 (= (nth ,attr-index attrs) ,ugid))))))
405
406 (defun eshell-pred-file-time (mod-char mod-type attr-index)
407 "Return a predicate to test whether a file matches a certain time."
408 (let* ((quantum 86400)
409 qual amount when open close end)
410 (when (memq (char-after) '(?M ?w ?h ?m ?s))
411 (setq quantum (char-after))
412 (cond
413 ((eq quantum ?M)
414 (setq quantum (* 60 60 24 30)))
415 ((eq quantum ?w)
416 (setq quantum (* 60 60 24 7)))
417 ((eq quantum ?h)
418 (setq quantum (* 60 60)))
419 ((eq quantum ?m)
420 (setq quantum 60))
421 ((eq quantum ?s)
422 (setq quantum 1)))
423 (forward-char))
424 (when (memq (char-after) '(?+ ?-))
425 (setq qual (char-after))
426 (forward-char))
427 (if (looking-at "[0-9]+")
428 (progn
429 (setq when (- (float-time)
430 (* (string-to-number (match-string 0))
431 quantum)))
432 (goto-char (match-end 0)))
433 (setq open (char-after))
434 (if (setq close (memq open '(?\( ?\[ ?\< ?\{)))
435 (setq close (car (last '(?\) ?\] ?\> ?\})
436 (length close))))
437 (setq close open))
438 (forward-char)
439 (setq end (eshell-find-delimiter open close))
440 (unless end
441 (error "Malformed %s time modifier `%c'" mod-type mod-char))
442 (let* ((file (buffer-substring (point) end))
443 (attrs (file-attributes file)))
444 (unless attrs
445 (error "Cannot stat file `%s'" file))
446 (setq when (float-time (nth attr-index attrs))))
447 (goto-char (1+ end)))
448 `(lambda (file)
449 (let ((attrs (file-attributes file)))
450 (if attrs
451 (,(if (eq qual ?-)
452 '<
453 (if (eq qual ?+)
454 '>
455 '=)) ,when (float-time
456 (nth ,attr-index attrs))))))))
457
458 (defun eshell-pred-file-type (type)
459 "Return a test which tests that the file is of a certain TYPE.
460 TYPE must be a character, and should be one of the possible options
461 that 'ls -l' will show in the first column of its display. "
462 (when (eq type ?%)
463 (setq type (char-after))
464 (if (memq type '(?b ?c))
465 (forward-char)
466 (setq type ?%)))
467 `(lambda (file)
468 (let ((attrs (eshell-file-attributes (directory-file-name file))))
469 (if attrs
470 (memq (aref (nth 8 attrs) 0)
471 ,(if (eq type ?%)
472 '(?b ?c)
473 (list 'quote (list type))))))))
474
475 (defsubst eshell-pred-file-mode (mode)
476 "Return a test which tests that MODE pertains to the file."
477 `(lambda (file)
478 (let ((modes (file-modes file)))
479 (if modes
480 (logand ,mode modes)))))
481
482 (defun eshell-pred-file-links ()
483 "Return a predicate to test whether a file has a given number of links."
484 (let (qual amount)
485 (when (memq (char-after) '(?- ?+))
486 (setq qual (char-after))
487 (forward-char))
488 (unless (looking-at "[0-9]+")
489 (error "Invalid file link count modifier `l'"))
490 (setq amount (string-to-number (match-string 0)))
491 (goto-char (match-end 0))
492 `(lambda (file)
493 (let ((attrs (eshell-file-attributes file)))
494 (if attrs
495 (,(if (eq qual ?-)
496 '<
497 (if (eq qual ?+)
498 '>
499 '=)) (nth 1 attrs) ,amount))))))
500
501 (defun eshell-pred-file-size ()
502 "Return a predicate to test whether a file is of a given size."
503 (let ((quantum 1) qual amount)
504 (when (memq (downcase (char-after)) '(?k ?m ?p))
505 (setq qual (downcase (char-after)))
506 (cond
507 ((eq qual ?k)
508 (setq quantum 1024))
509 ((eq qual ?m)
510 (setq quantum (* 1024 1024)))
511 ((eq qual ?p)
512 (setq quantum 512)))
513 (forward-char))
514 (when (memq (char-after) '(?- ?+))
515 (setq qual (char-after))
516 (forward-char))
517 (unless (looking-at "[0-9]+")
518 (error "Invalid file size modifier `L'"))
519 (setq amount (* (string-to-number (match-string 0)) quantum))
520 (goto-char (match-end 0))
521 `(lambda (file)
522 (let ((attrs (eshell-file-attributes file)))
523 (if attrs
524 (,(if (eq qual ?-)
525 '<
526 (if (eq qual ?+)
527 '>
528 '=)) (nth 7 attrs) ,amount))))))
529
530 (defun eshell-pred-substitute (&optional repeat)
531 "Return a modifier function that will substitute matches."
532 (let ((delim (char-after))
533 match replace end)
534 (forward-char)
535 (setq end (eshell-find-delimiter delim delim nil nil t)
536 match (buffer-substring-no-properties (point) end))
537 (goto-char (1+ end))
538 (setq end (eshell-find-delimiter delim delim nil nil t)
539 replace (buffer-substring-no-properties (point) end))
540 (goto-char (1+ end))
541 (if repeat
542 `(lambda (lst)
543 (mapcar
544 (function
545 (lambda (str)
546 (let ((i 0))
547 (while (setq i (string-match ,match str i))
548 (setq str (replace-match ,replace t nil str))))
549 str)) lst))
550 `(lambda (lst)
551 (mapcar
552 (function
553 (lambda (str)
554 (if (string-match ,match str)
555 (setq str (replace-match ,replace t nil str)))
556 str)) lst)))))
557
558 (defun eshell-include-members (&optional invert-p)
559 "Include only lisp members matching a regexp."
560 (let ((delim (char-after))
561 regexp end)
562 (forward-char)
563 (setq end (eshell-find-delimiter delim delim nil nil t)
564 regexp (buffer-substring-no-properties (point) end))
565 (goto-char (1+ end))
566 `(lambda (lst)
567 (eshell-winnow-list
568 lst nil '((lambda (elem)
569 ,(if invert-p
570 `(not (string-match ,regexp elem))
571 `(string-match ,regexp elem))))))))
572
573 (defun eshell-join-members ()
574 "Return a modifier function that join matches."
575 (let ((delim (char-after))
576 str end)
577 (if (not (memq delim '(?' ?/)))
578 (setq delim " ")
579 (forward-char)
580 (setq end (eshell-find-delimiter delim delim nil nil t)
581 str (buffer-substring-no-properties (point) end))
582 (goto-char (1+ end)))
583 `(lambda (lst)
584 (mapconcat 'identity lst ,str))))
585
586 (defun eshell-split-members ()
587 "Return a modifier function that splits members."
588 (let ((delim (char-after))
589 sep end)
590 (when (memq delim '(?' ?/))
591 (forward-char)
592 (setq end (eshell-find-delimiter delim delim nil nil t)
593 sep (buffer-substring-no-properties (point) end))
594 (goto-char (1+ end)))
595 `(lambda (lst)
596 (mapcar
597 (function
598 (lambda (str)
599 (split-string str ,sep))) lst))))
600
601 (provide 'em-pred)
602
603 ;; Local Variables:
604 ;; generated-autoload-file: "esh-groups.el"
605 ;; End:
606
607 ;;; em-pred.el ends here