Commit | Line | Data |
---|---|---|
861345b4 | 1 | ;;; -*-lisp-*- |
2 | ;;; | |
3 | ;;; $Id$ | |
4 | ;;; | |
5 | ;;; Option parser, standard issue | |
6 | ;;; | |
7 | ;;; (c) 2005 Straylight/Edgeware | |
8 | ;;; | |
9 | ||
10 | ;;;----- Licensing notice --------------------------------------------------- | |
11 | ;;; | |
12 | ;;; This program is free software; you can redistribute it and/or modify | |
13 | ;;; it under the terms of the GNU General Public License as published by | |
14 | ;;; the Free Software Foundation; either version 2 of the License, or | |
15 | ;;; (at your option) any later version. | |
16 | ;;; | |
17 | ;;; This program is distributed in the hope that it will be useful, | |
18 | ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 | ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
20 | ;;; GNU General Public License for more details. | |
21 | ;;; | |
22 | ;;; You should have received a copy of the GNU General Public License | |
23 | ;;; along with this program; if not, write to the Free Software Foundation, | |
24 | ;;; Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. | |
25 | ||
02866e07 MW |
26 | ;;;-------------------------------------------------------------------------- |
27 | ;;; Packages. | |
28 | ||
861345b4 | 29 | (defpackage #:mdw.optparse |
30 | (:use #:common-lisp #:mdw.base #:mdw.sys-base #:mdw.str) | |
31 | (:export #:exit #:*program-name* #:*command-line-strings* | |
32 | #:moan #:die | |
33 | #:option #:optionp #:make-option | |
34 | #:opt-short-name #:opt-long-name #:opt-tag #:opt-negated-tag | |
35 | #:opt-arg-name #:opt-arg-optional-p #:opt-documentation | |
36 | #:option-parser #:make-option-parser #:option-parser-p | |
37 | #:op-options #:op-non-option #:op-long-only-p #:op-numeric-p | |
38 | #:op-negated-numeric-p #:op-negated-p | |
39 | #:option-parse-error | |
40 | #:option-parse-remainder #:option-parse-next #:option-parse-try | |
41 | #:with-unix-error-reporting | |
42 | #:defopthandler #:invoke-option-handler | |
43 | #:set #:clear #:inc #:dec #:read #:int #:string | |
44 | #:keyword #:list | |
45 | #:parse-option-form #:options | |
46 | #:simple-usage #:show-usage #:show-version #:show-help | |
47 | #:sanity-check-option-list)) | |
48 | ||
49 | (in-package #:mdw.optparse) | |
50 | ||
02866e07 | 51 | ;;;-------------------------------------------------------------------------- |
861345b4 | 52 | ;;; Standard error-reporting functions. |
53 | ||
54 | (defun moan (msg &rest args) | |
55 | "Report an error message in the usual way." | |
56 | (format *error-output* "~&~A: ~?~%" *program-name* msg args)) | |
57 | (defun die (&rest args) | |
58 | "Report an error message and exit." | |
59 | (apply #'moan args) | |
60 | (exit 1)) | |
61 | ||
02866e07 | 62 | ;;;-------------------------------------------------------------------------- |
861345b4 | 63 | ;;; The main option parser. |
64 | ||
65 | (defstruct (option (:predicate optionp) | |
66 | (:conc-name opt-) | |
67 | (:print-function | |
68 | (lambda (o s k) | |
69 | (declare (ignore k)) | |
70 | (format s | |
71 | "#<option~@[ -~C,~]~@[ --~A~]~:[~2*~;~:[=~A~;[=~A]~]~]~@[ ~S~]>" | |
72 | (opt-short-name o) | |
73 | (opt-long-name o) | |
74 | (opt-arg-name o) | |
75 | (opt-arg-optional-p o) | |
76 | (opt-arg-name o) | |
77 | (opt-documentation o)))) | |
78 | (:constructor %make-option) | |
79 | (:constructor make-option | |
80 | (long-name | |
81 | short-name | |
82 | &optional | |
83 | arg-name | |
84 | &key | |
85 | (tag (intern (string-upcase long-name) | |
86 | :keyword)) | |
87 | negated-tag | |
88 | arg-optional-p | |
89 | doc | |
90 | (documentation doc)))) | |
91 | "Describes a command-line option. Slots: | |
92 | ||
93 | LONG-NAME The option's long name. If this is null, the `option' is | |
94 | just a banner to be printed in the program's help text. | |
95 | ||
96 | TAG The value to be returned if this option is encountered. If | |
97 | this is a function, instead, the function is called with the | |
98 | option's argument or nil. | |
99 | ||
100 | NEGATED-TAG As for TAG, but used if the negated form of the option is | |
101 | found. If this is nil (the default), the option cannot be | |
102 | negated. | |
103 | ||
104 | SHORT-NAME The option's short name. This must be a single character, or | |
105 | nil if the option has no short name. | |
106 | ||
107 | ARG-NAME The name of the option's argument, a string. If this is nil, | |
108 | the option doesn't accept an argument. The name is shown in | |
109 | the help text. | |
110 | ||
111 | ARG-OPTIONAL-P If non-nil, the option's argument is optional. This is | |
112 | ignored unless ARG-NAME is non-null. | |
113 | ||
114 | DOCUMENTATION The help text for this option. It is automatically | |
115 | line-wrapped. If nil, the option is omitted from the help | |
116 | text. | |
117 | ||
118 | Usually, one won't use make-option, but use the option macro instead." | |
119 | (long-name nil :type (or null string)) | |
120 | (tag nil :type t) | |
121 | (negated-tag nil :type t) | |
122 | (short-name nil :type (or null character)) | |
123 | (arg-name nil :type (or null string)) | |
124 | (arg-optional-p nil :type t) | |
125 | (documentation nil :type (or null string))) | |
126 | ||
127 | (defstruct (option-parser (:conc-name op-) | |
128 | (:constructor make-option-parser | |
129 | (argstmp | |
130 | options | |
131 | &key | |
132 | (non-option :skip) | |
133 | ((:numericp numeric-p)) | |
134 | negated-numeric-p | |
135 | long-only-p | |
136 | &aux | |
137 | (args (cons nil argstmp)) | |
138 | (next args) | |
139 | (negated-p (or negated-numeric-p | |
140 | (some | |
141 | #'opt-negated-tag | |
142 | options)))))) | |
143 | "An option parser object. Slots: | |
144 | ||
145 | ARGS The arguments to be parsed. Usually this will be | |
146 | *command-line-strings*. | |
147 | ||
148 | OPTIONS List of option structures describing the acceptable options. | |
149 | ||
150 | NON-OPTION Behaviour when encountering a non-option argument. The | |
151 | default is :skip. Allowable values are: | |
152 | :skip -- pretend that it appeared after the option | |
153 | arguments; this is the default behaviour of GNU getopt | |
154 | :stop -- stop parsing options, leaving the remaining | |
155 | command line unparsed | |
156 | :return -- return :non-option and the argument word | |
157 | ||
158 | NUMERIC-P Non-nil tag (as for options) if numeric options (e.g., -43) | |
159 | are to be allowed. The default is nil. (Anomaly: the | |
160 | keyword for this argument is :numericp.) | |
161 | ||
162 | NEGATED-NUMERIC-P | |
163 | Non-nil tag (as for options) if numeric options (e.g., -43) | |
164 | can be negated. This is not the same thing as a negative | |
165 | numeric option! | |
166 | ||
167 | LONG-ONLY-P A misnomer inherited from GNU getopt. Whether to allow | |
168 | long options to begin with a single dash. Short options are | |
169 | still allowed, and may be cuddled as usual. The default is | |
170 | nil." | |
171 | (args nil :type list) | |
172 | (options nil :type list) | |
173 | (non-option :skip :type (or function (member :skip :stop :return))) | |
174 | (next nil :type list) | |
175 | (short-opt nil :type (or null string)) | |
176 | (short-opt-index 0 :type fixnum) | |
177 | (short-opt-neg-p nil :type t) | |
178 | (long-only-p nil :type t) | |
179 | (numeric-p nil :type t) | |
180 | (negated-numeric-p nil :type t) | |
181 | (negated-p nil :type t)) | |
182 | ||
183 | (define-condition option-parse-error (error simple-condition) | |
184 | () | |
185 | (:documentation "Indicates an error found while parsing options. Probably | |
186 | not that useful.")) | |
187 | ||
188 | (defun option-parse-error (msg &rest args) | |
189 | "Signal an option-parse-error with the given message and arguments." | |
190 | (error (make-condition 'option-parse-error | |
191 | :format-control msg | |
192 | :format-arguments args))) | |
193 | ||
194 | (defun option-parse-remainder (op) | |
195 | "Returns the unparsed remainder of the command line." | |
196 | (cdr (op-args op))) | |
197 | ||
198 | (defun option-parse-next (op) | |
199 | "The main option-parsing function. OP is an option-parser object, | |
200 | initialized appropriately. Returns two values, OPT and ARG: OPT is the tag | |
201 | of the next option read, and ARG is the argument attached to it, or nil if | |
202 | there was no argument. If there are no more options, returns nil twice. | |
203 | Options whose TAG is a function aren't returned; instead, the tag function is | |
204 | called, with the option argument (or nil) as the only argument. It is safe | |
205 | for tag functions to throw out of option-parse-next, if they desparately need | |
206 | to. (This is the only way to actually get option-parse-next to return a | |
207 | function value, should that be what you want.) | |
208 | ||
209 | While option-parse-next is running, there is a restart `skip-option' which | |
210 | moves on to the next option. Error handlers should use this to resume after | |
211 | parsing errors." | |
212 | (loop | |
213 | (labels ((ret (opt &optional arg) | |
214 | (return-from option-parse-next (values opt arg))) | |
215 | (finished () | |
216 | (setf (op-next op) nil) | |
217 | (ret nil nil)) | |
218 | (peek-arg () | |
219 | (cadr (op-next op))) | |
220 | (more-args-p () | |
221 | (and (op-next op) | |
222 | (cdr (op-next op)))) | |
223 | (skip-arg () | |
224 | (setf (op-next op) (cdr (op-next op)))) | |
225 | (eat-arg () | |
226 | (setf (cdr (op-next op)) (cddr (op-next op)))) | |
227 | (get-arg () | |
228 | (prog1 (peek-arg) (eat-arg))) | |
229 | (process-option (o name negp &key arg argfunc) | |
230 | (cond ((not (opt-arg-name o)) | |
231 | (when arg | |
232 | (option-parse-error | |
233 | "Option `~A' does not accept arguments" | |
234 | name))) | |
235 | (arg) | |
236 | (argfunc | |
237 | (setf arg (funcall argfunc))) | |
238 | ((opt-arg-optional-p o)) | |
239 | ((more-args-p) | |
240 | (setf arg (get-arg))) | |
241 | (t | |
242 | (option-parse-error "Option `~A' requires an argument" | |
243 | name))) | |
244 | (let ((how (if negp (opt-negated-tag o) (opt-tag o)))) | |
245 | (if (functionp how) | |
246 | (funcall how arg) | |
247 | (ret how arg)))) | |
248 | (process-long-option (arg start negp) | |
249 | (when (and (not negp) | |
250 | (op-negated-p op) | |
251 | (> (length arg) (+ start 3)) | |
252 | (string= arg "no-" | |
253 | :start1 start :end1 (+ start 3))) | |
254 | (incf start 3) | |
255 | (setf negp t)) | |
256 | (let* ((matches nil) | |
257 | (eqpos (position #\= arg :start start)) | |
258 | (len (or eqpos (length arg))) | |
259 | (optname (subseq arg 0 len)) | |
260 | (len-2 (- len start))) | |
261 | (dolist (o (op-options op)) | |
262 | (cond ((or (not (stringp (opt-long-name o))) | |
263 | (and negp (not (opt-negated-tag o))) | |
264 | (< (length (opt-long-name o)) len-2) | |
265 | (string/= optname (opt-long-name o) | |
266 | :start1 start :end2 len-2))) | |
267 | ((= (length (opt-long-name o)) len-2) | |
268 | (setf matches (list o)) | |
269 | (return)) | |
270 | (t | |
271 | (push o matches)))) | |
272 | (cond ((null matches) | |
273 | (option-parse-error "Unknown option `~A'" optname)) | |
274 | ((cdr matches) | |
275 | (option-parse-error | |
276 | "~ | |
277 | Ambiguous long option `~A' -- could be any of:~{~% --~A~}" | |
278 | optname | |
279 | (mapcar #'opt-long-name matches)))) | |
280 | (process-option (car matches) | |
281 | optname | |
282 | negp | |
283 | :arg (and eqpos | |
284 | (subseq arg (1+ eqpos))))))) | |
285 | (with-simple-restart (skip-option "Skip this bogus option.") | |
286 | (cond | |
287 | ;; | |
288 | ;; We're embroiled in short options: handle them. | |
289 | ((op-short-opt op) | |
290 | (if (>= (op-short-opt-index op) (length (op-short-opt op))) | |
291 | (setf (op-short-opt op) nil) | |
292 | (let* ((str (op-short-opt op)) | |
293 | (i (op-short-opt-index op)) | |
294 | (ch (char str i)) | |
295 | (negp (op-short-opt-neg-p op)) | |
296 | (name (format nil "~C~A" (if negp #\+ #\-) ch)) | |
297 | (o (find ch (op-options op) :key #'opt-short-name))) | |
298 | (incf i) | |
299 | (setf (op-short-opt-index op) i) | |
300 | (when (or (not o) | |
301 | (and negp (not (opt-negated-tag o)))) | |
302 | (option-parse-error "Unknown option `~A'" name)) | |
303 | (process-option o | |
304 | name | |
305 | negp | |
306 | :argfunc | |
307 | (and (< i (length str)) | |
308 | (lambda () | |
309 | (prog1 | |
310 | (subseq str i) | |
311 | (setf (op-short-opt op) | |
312 | nil)))))))) | |
313 | ;; | |
314 | ;; End of the list. Say we've finished. | |
315 | ((not (more-args-p)) | |
316 | (finished)) | |
317 | ;; | |
318 | ;; Process the next option. | |
319 | (t | |
320 | (let ((arg (peek-arg))) | |
321 | (cond | |
322 | ;; | |
323 | ;; Non-option. Decide what to do. | |
324 | ((or (<= (length arg) 1) | |
325 | (and (char/= (char arg 0) #\-) | |
326 | (or (char/= (char arg 0) #\+) | |
327 | (not (op-negated-p op))))) | |
328 | (case (op-non-option op) | |
329 | (:skip (skip-arg)) | |
330 | (:stop (finished)) | |
331 | (:return (eat-arg) | |
332 | (ret :non-option arg)) | |
333 | (t (eat-arg) | |
334 | (funcall (op-non-option op) arg)))) | |
335 | ;; | |
336 | ;; Double-hyphen. Stop right now. | |
337 | ((string= arg "--") | |
338 | (eat-arg) | |
339 | (finished)) | |
340 | ;; | |
341 | ;; Numbers. Check these before long options, since `--43' is | |
342 | ;; not a long option. | |
343 | ((and (op-numeric-p op) | |
344 | (or (char= (char arg 0) #\-) | |
345 | (op-negated-numeric-p op)) | |
346 | (or (and (digit-char-p (char arg 1)) | |
347 | (every #'digit-char-p (subseq arg 2))) | |
348 | (and (or (char= (char arg 1) #\-) | |
349 | (char= (char arg 1) #\+)) | |
350 | (>= (length arg) 3) | |
351 | (digit-char-p (char arg 2)) | |
352 | (every #'digit-char-p (subseq arg 3))))) | |
353 | (eat-arg) | |
354 | (let ((negp (char= (char arg 0) #\+)) | |
355 | (num (parse-integer arg :start 1))) | |
356 | (when (and negp (eq (op-negated-numeric-p op) :-)) | |
357 | (setf num (- num)) | |
358 | (setf negp nil)) | |
359 | (let ((how (if negp | |
360 | (op-negated-numeric-p op) | |
361 | (op-numeric-p op)))) | |
362 | (if (functionp how) | |
363 | (funcall how num) | |
364 | (ret (if negp :negated-numeric :numeric) num))))) | |
365 | ;; | |
366 | ;; Long option. Find the matching option-spec and process | |
367 | ;; it. | |
368 | ((and (char= (char arg 0) #\-) | |
369 | (char= (char arg 1) #\-)) | |
370 | (eat-arg) | |
371 | (process-long-option arg 2 nil)) | |
372 | ;; | |
373 | ;; Short options. All that's left. | |
374 | (t | |
375 | (eat-arg) | |
376 | (let ((negp (char= (char arg 0) #\+)) | |
377 | (ch (char arg 1))) | |
378 | (cond ((and (op-long-only-p op) | |
379 | (not (member ch (op-options op) | |
380 | :key #'opt-short-name))) | |
381 | (process-long-option arg 1 negp)) | |
382 | (t | |
383 | (setf (op-short-opt op) arg | |
384 | (op-short-opt-index op) 1 | |
385 | (op-short-opt-neg-p op) negp))))))))))))) | |
386 | ||
387 | (defmacro option-parse-try (&body body) | |
388 | "Report errors encountered while parsing options, and continue struggling | |
389 | along. Also establishes a restart `stop-parsing'. Returns t if parsing | |
390 | completed successfully, or nil if errors occurred." | |
391 | (with-gensyms (retcode) | |
392 | `(let ((,retcode t)) | |
393 | (restart-case | |
394 | (handler-bind | |
395 | ((option-parse-error | |
396 | (lambda (cond) | |
397 | (setf ,retcode nil) | |
398 | (moan "~A" cond) | |
399 | (dolist (rn '(skip-option stop-parsing)) | |
400 | (let ((r (find-restart rn))) | |
401 | (when r (invoke-restart r))))))) | |
402 | ,@body) | |
403 | (stop-parsing () | |
404 | :report "Give up parsing options." | |
405 | (setf ,retcode nil))) | |
406 | ,retcode))) | |
407 | ||
408 | (defmacro with-unix-error-reporting ((&key) &body body) | |
409 | "Evaluate BODY with errors reported in the standard Unix fashion." | |
410 | (with-gensyms (cond) | |
411 | `(handler-case | |
412 | (progn ,@body) | |
413 | (simple-condition (,cond) | |
414 | (die (simple-condition-format-control ,cond) | |
415 | (simple-condition-format-arguments ,cond))) | |
416 | (error (,cond) | |
417 | (die "~A" ,cond))))) | |
418 | ||
02866e07 | 419 | ;;;-------------------------------------------------------------------------- |
861345b4 | 420 | ;;; Standard option handlers. |
421 | ||
422 | (defmacro defopthandler (name (var &optional (arg (gensym))) | |
423 | (&rest args) | |
424 | &body body) | |
425 | "Define an option handler function NAME. Option handlers update a | |
426 | generalized variable, which may be referred to as VAR in the BODY, based on | |
427 | some parameters (the ARGS) and the value of an option-argument named ARG." | |
428 | (let ((func (intern (format nil "OPTHANDLER/~:@(~A~)" name)))) | |
429 | `(progn | |
430 | (setf (get ',name 'opthandler) ',func) | |
431 | (defun ,func (,var ,arg ,@args) | |
432 | (with-locatives ,var | |
433 | (declare (ignorable ,arg)) | |
434 | ,@body)) | |
435 | ',name))) | |
436 | ||
437 | (defun parse-c-integer (string &key radix (start 0) end) | |
438 | "Parse STRING, or at least the parts of it between START and END, according | |
439 | to the standard C rules. Well, almost: the 0 and 0x prefixes are accepted, | |
440 | but so too are 0o (Haskell) and 0b (original); also RADIX_DIGITS is accepted, | |
441 | for any radix between 2 and 36. Prefixes are only accepted if RADIX is nil. | |
442 | Returns two values: the integer parsed (or nil if there wasn't enough for a | |
443 | sensible parse), and the index following the characters of the integer." | |
444 | (unless end (setf end (length string))) | |
202c91a3 MW |
445 | (labels ((simple (i r goodp sgn) |
446 | (multiple-value-bind | |
447 | (a i) | |
448 | (if (and (< i end) | |
449 | (digit-char-p (char string i) r)) | |
450 | (parse-integer string | |
451 | :start i :end end | |
452 | :radix r | |
453 | :junk-allowed t) | |
454 | (values nil i)) | |
455 | (values (if a (* sgn a) (and goodp 0)) i))) | |
861345b4 | 456 | (get-radix (i r sgn) |
202c91a3 | 457 | (cond (r (simple i r nil sgn)) |
861345b4 | 458 | ((>= i end) (values nil i)) |
459 | ((and (char= (char string i) #\0) | |
460 | (>= (- end i) 2)) | |
461 | (case (char string (1+ i)) | |
202c91a3 MW |
462 | (#\x (simple (+ i 2) 16 nil sgn)) |
463 | (#\o (simple (+ i 2) 8 nil sgn)) | |
464 | (#\b (simple (+ i 2) 2 nil sgn)) | |
465 | (t (simple (1+ i) 8 t sgn)))) | |
861345b4 | 466 | (t |
467 | (multiple-value-bind | |
202c91a3 MW |
468 | (r i) |
469 | (simple i 10 nil +1) | |
861345b4 | 470 | (cond ((not r) (values nil i)) |
471 | ((and (< i end) | |
472 | (char= (char string i) #\_) | |
473 | (<= 2 r 36)) | |
202c91a3 | 474 | (simple (1+ i) r nil sgn)) |
861345b4 | 475 | (t |
476 | (values (* r sgn) i)))))))) | |
477 | (cond ((>= start end) (values nil start)) | |
478 | ((char= (char string start) #\-) | |
479 | (get-radix (1+ start) radix -1)) | |
480 | ((char= (char string start) #\+) | |
481 | (get-radix (1+ start) radix +1)) | |
482 | (t | |
483 | (get-radix start radix +1))))) | |
484 | ||
485 | (defun invoke-option-handler (handler loc arg args) | |
486 | "Call the HANDLER function, giving it LOC to update, the option-argument | |
487 | ARG, and the remaining ARGS." | |
488 | (apply (if (functionp handler) handler | |
489 | (fdefinition (get handler 'opthandler))) | |
490 | loc | |
491 | arg | |
492 | args)) | |
493 | ||
494 | (defopthandler set (var) (&optional (value t)) | |
495 | "Sets VAR to VALUE; defaults to t." | |
496 | (setf var value)) | |
497 | (defopthandler clear (var) (&optional (value nil)) | |
498 | "Sets VAR to VALUE; defaults to nil." | |
499 | (setf var value)) | |
500 | (defopthandler inc (var) (&optional max (step 1)) | |
501 | "Increments VAR by STEP (defaults to 1), but not greater than MAX (default | |
502 | nil for no maximum). No errors are signalled." | |
503 | (incf var step) | |
504 | (when (>= var max) | |
505 | (setf var max))) | |
506 | (defopthandler dec (var) (&optional min (step 1)) | |
507 | "Decrements VAR by STEP (defaults to 1), but not less than MIN (default nil | |
508 | for no maximum). No errors are signalled." | |
509 | (decf var step) | |
510 | (when (<= var min) | |
511 | (setf var min))) | |
512 | (defopthandler read (var arg) () | |
513 | "Stores in VAR the Lisp object found by reading the ARG. Evaluation is | |
514 | forbidden while reading ARG. If there is an error during reading, an error | |
515 | of type option-parse-error is signalled." | |
516 | (handler-case | |
517 | (let ((*read-eval* nil)) | |
518 | (multiple-value-bind (x end) (read-from-string arg t) | |
519 | (unless (>= end (length arg)) | |
520 | (option-parse-error "Junk at end of argument `~A'" arg)) | |
521 | (setf var x))) | |
522 | (error (cond) | |
523 | (option-parse-error (format nil "~A" cond))))) | |
524 | (defopthandler int (var arg) (&key radix min max) | |
525 | "Stores in VAR the integer read from the ARG. Integers are parsed | |
526 | according to C rules, which is normal in Unix; the RADIX may be nil to allow | |
527 | radix prefixes, or an integer between 2 and 36. An option-parse-error is | |
528 | signalled if the ARG is not a valid integer, or if it is not between MIN and | |
529 | MAX (either of which may be nil if no lower resp. upper bound is wanted)." | |
530 | (multiple-value-bind (v end) (parse-c-integer arg :radix radix) | |
531 | (unless (and v (>= end (length arg))) | |
532 | (option-parse-error "Bad integer `~A'" arg)) | |
533 | (when (or (and min (< v min)) | |
534 | (and max (> v max))) | |
535 | (option-parse-error | |
536 | "Integer ~A out of range (must have ~@[~D <= ~]x~@[ <= ~D~])" | |
537 | arg min max)) | |
538 | (setf var v))) | |
539 | (defopthandler string (var arg) () | |
540 | "Stores ARG in VAR, just as it is." | |
541 | (setf var arg)) | |
542 | (defopthandler keyword (var arg) (&rest valid) | |
543 | (if (null valid) | |
544 | (setf var (intern (string-upcase arg) :keyword)) | |
545 | (let ((matches nil) | |
546 | (guess (string-upcase arg)) | |
547 | (len (length arg))) | |
548 | (dolist (k valid) | |
549 | (let* ((kn (symbol-name k)) | |
550 | (klen (length kn))) | |
551 | (cond ((string= kn guess) | |
552 | (setf matches (list k)) | |
553 | (return)) | |
554 | ((and (< len klen) | |
555 | (string= guess kn :end2 len)) | |
556 | (push k matches))))) | |
557 | (case (length matches) | |
558 | (0 (option-parse-error "Argument `~A' invalid: must be one of:~ | |
559 | ~{~%~8T~(~A~)~}" | |
560 | arg valid)) | |
561 | (1 (setf var (car matches))) | |
562 | (t (option-parse-error "Argument `~A' ambiguous: may be any of:~ | |
563 | ~{~%~8T~(~A~)~}" | |
564 | arg matches)))))) | |
565 | (defopthandler list (var arg) (&optional handler &rest handler-args) | |
566 | "Collect ARGs in a list at VAR. ARGs are translated by the HANDLER first, | |
567 | if specified. If not, it's as if you asked for `string'." | |
568 | (when handler | |
569 | (invoke-option-handler handler (locf arg) arg handler-args)) | |
570 | (setf var (nconc var (list arg)))) | |
571 | ||
572 | (compile-time-defun parse-option-form (form) | |
573 | "Does the heavy lifting for parsing an option form. See the docstring for | |
574 | the `option' macro for details of the syntax." | |
575 | (flet ((doc (form) | |
576 | (cond ((stringp form) form) | |
577 | ((null (cdr form)) (car form)) | |
578 | (t `(format nil ,@form)))) | |
579 | (docp (form) | |
580 | (or (stringp form) | |
581 | (and (consp form) | |
582 | (stringp (car form)))))) | |
583 | (if (and (docp (car form)) | |
584 | (null (cdr form))) | |
585 | `(%make-option :documentation ,(doc (car form))) | |
586 | (let (long-name short-name | |
587 | arg-name arg-optional-p | |
588 | tag negated-tag | |
589 | doc) | |
590 | (dolist (f form) | |
591 | (cond ((and (or (not tag) (not negated-tag)) | |
592 | (or (keywordp f) | |
593 | (and (consp f) | |
594 | (member (car f) '(lambda function))))) | |
595 | (if tag | |
596 | (setf negated-tag f) | |
597 | (setf tag f))) | |
598 | ((and (not long-name) | |
599 | (or (rationalp f) | |
600 | (symbolp f) | |
601 | (stringp f))) | |
602 | (setf long-name (if (stringp f) f | |
603 | (format nil "~(~A~)" f)))) | |
604 | ((and (not short-name) | |
605 | (characterp f)) | |
606 | (setf short-name f)) | |
607 | ((and (not doc) | |
608 | (docp f)) | |
609 | (setf doc (doc f))) | |
610 | ((and (consp f) (symbolp (car f))) | |
611 | (case (car f) | |
612 | (:arg (setf arg-name (cadr f))) | |
613 | (:opt-arg (setf arg-name (cadr f)) | |
614 | (setf arg-optional-p t)) | |
615 | (:doc (setf doc (doc (cdr f)))) | |
616 | (t (let ((handler (get (car f) 'opthandler))) | |
617 | (unless handler | |
618 | (error "No handler `~S' defined." (car f))) | |
619 | (let* ((var (cadr f)) | |
620 | (arg (gensym)) | |
621 | (thunk `#'(lambda (,arg) | |
622 | (,handler (locf ,var) | |
623 | ,arg | |
624 | ,@(cddr f))))) | |
625 | (if tag | |
626 | (setf negated-tag thunk) | |
627 | (setf tag thunk))))))) | |
628 | (t | |
629 | (error "Unexpected thing ~S in option form." f)))) | |
630 | `(make-option ,long-name ,short-name ,arg-name | |
631 | ,@(and arg-optional-p `(:arg-optional-p t)) | |
632 | ,@(and tag `(:tag ,tag)) | |
633 | ,@(and negated-tag `(:negated-tag ,negated-tag)) | |
634 | ,@(and doc `(:documentation ,doc))))))) | |
635 | ||
636 | (defmacro options (&rest optlist) | |
637 | "More convenient way of initializing options. The OPTLIST is a list of | |
638 | OPTFORMS. Each OPTFORM is either a banner string, or a list of | |
639 | items. Acceptable items are interpreted as follows: | |
640 | ||
641 | KEYWORD or FUNCTION | |
642 | If no TAG is set yet, then as a TAG; otherwise as the NEGATED-TAG. | |
643 | ||
644 | STRING (or SYMBOL or RATIONAL) | |
645 | If no LONG-NAME seen yet, then the LONG-NAME. For symbols and rationals, | |
646 | the item is converted to a string and squashed to lower-case. | |
647 | ||
648 | CHARACTER | |
649 | The SHORT-NAME. | |
650 | ||
651 | STRING or (STRING STUFF...) | |
652 | If no DOCUMENTATION set yet, then the DOCUMENTATION string. A string is | |
653 | used as-is; a list is considered to be a `format' string and its | |
654 | arguments. This is evaluated at standard evaluation time: the option | |
655 | structure returned contains a simple documentation string. | |
656 | ||
657 | (:ARG NAME) | |
658 | Set the ARG-NAME. | |
659 | ||
660 | (:OPT-ARG NAME) | |
661 | Set the ARG-NAME, and also set ARG-OPTIONAL-P. | |
662 | ||
663 | (HANDLER VAR ARGS...) | |
664 | If no TAG is set yet, attach the HANDLER to this option, giving it ARGS. | |
665 | Otherwise, set the NEGATED-TAG." | |
666 | `(list ,@(mapcar (lambda (form) | |
667 | (if (stringp form) | |
668 | `(%make-option :documentation ,form) | |
669 | (parse-option-form form))) | |
670 | optlist))) | |
671 | ||
02866e07 | 672 | ;;;-------------------------------------------------------------------------- |
861345b4 | 673 | ;;; Support stuff for help and usage messages |
674 | ||
675 | (defun print-text (string | |
676 | &optional | |
677 | (stream *standard-output*) | |
678 | &key | |
679 | (start 0) | |
680 | (end nil)) | |
681 | "Prints STRING to a pretty-printed STREAM, breaking it at whitespace and | |
682 | newlines in the obvious way. Stuff between square brackets is not broken: | |
683 | this makes usage messages work better." | |
684 | (let ((i start) | |
685 | (nest 0) | |
686 | (splitp nil)) | |
687 | (flet ((emit () | |
688 | (write-string string stream :start start :end i) | |
689 | (setf start i))) | |
690 | (unless end | |
691 | (setf end (length string))) | |
692 | (loop | |
693 | (unless (< i end) | |
694 | (emit) | |
695 | (return)) | |
696 | (let ((ch (char string i))) | |
697 | (cond ((char= ch #\newline) | |
698 | (emit) | |
699 | (incf start) | |
700 | (pprint-newline :mandatory stream)) | |
701 | ((whitespace-char-p ch) | |
702 | (when (zerop nest) | |
703 | (setf splitp t))) | |
704 | (t | |
705 | (when splitp | |
706 | (emit) | |
707 | (pprint-newline :fill stream)) | |
708 | (setf splitp nil) | |
709 | (case ch | |
710 | (#\[ (incf nest)) | |
711 | (#\] (when (plusp nest) (decf nest)))))) | |
712 | (incf i)))))) | |
713 | ||
714 | (defun simple-usage (opts &optional mandatory-args) | |
715 | "Build a simple usage list from a list of options, and (optionally) | |
716 | mandatory argument names." | |
717 | (let (short-simple long-simple short-arg long-arg) | |
718 | (dolist (o opts) | |
719 | (cond ((not (and (opt-documentation o) | |
720 | (opt-long-name o)))) | |
721 | ((and (opt-short-name o) (opt-arg-name o)) | |
722 | (push o short-arg)) | |
723 | ((opt-short-name o) | |
724 | (push o short-simple)) | |
725 | ((opt-arg-name o) | |
726 | (push o long-arg)) | |
727 | (t | |
728 | (push o long-simple)))) | |
729 | (list | |
730 | (nconc (and short-simple | |
731 | (list (format nil "[-~{~C~}]" | |
732 | (sort (mapcar #'opt-short-name short-simple) | |
733 | #'char<)))) | |
734 | (and long-simple | |
735 | (mapcar (lambda (o) | |
736 | (format nil "[--~A]" (opt-long-name o))) | |
737 | (sort long-simple #'string< :key #'opt-long-name))) | |
738 | (and short-arg | |
739 | (mapcar (lambda (o) | |
740 | (format nil "~:[[-~C ~A]~;[-~C[~A]]~]" | |
741 | (opt-arg-optional-p o) | |
742 | (opt-short-name o) | |
743 | (opt-arg-name o))) | |
744 | (sort short-arg #'char-lessp | |
745 | :key #'opt-short-name))) | |
746 | (and long-arg | |
747 | (mapcar (lambda (o) | |
748 | (format nil "~:[[--~A ~A]~;[--~A[=~A]]~]" | |
749 | (opt-arg-optional-p o) | |
750 | (opt-long-name o) | |
751 | (opt-arg-name o))) | |
752 | (sort long-arg #'string-lessp | |
753 | :key #'opt-long-name))) | |
754 | (listify mandatory-args))))) | |
755 | ||
756 | (defun show-usage (prog usage &optional (stream *standard-output*)) | |
757 | "Basic usage-showing function. PROG is the program name, probable from | |
758 | *command-line-strings*. USAGE is a list of possible usages of the program, | |
759 | each of which is a list of items to be supplied by the user. In simple | |
760 | cases, a single string is sufficient." | |
761 | (pprint-logical-block (stream nil :prefix "Usage: ") | |
762 | (dolist (u (listify usage)) | |
763 | (pprint-logical-block (stream nil :prefix (format nil "~A " prog)) | |
764 | (format stream "~{~A ~:_~}" (listify u))) | |
765 | (pprint-newline :mandatory stream)))) | |
766 | ||
767 | (defun show-help (prog ver usage opts &optional (stream *standard-output*)) | |
768 | "Basic help-showing function. PROG is the program name, probably from | |
769 | *command-line-strings*. VER is the program's version number. USAGE is a | |
770 | list of the possible usages of the program, each of which may be a list of | |
771 | items to be supplied. OPTS is the list of supported options, as provided to | |
772 | the options parser. STREAM is the stream to write on." | |
773 | (format stream "~A, version ~A~2%" prog ver) | |
774 | (show-usage prog usage stream) | |
775 | (terpri stream) | |
776 | (let (newlinep) | |
777 | (dolist (o opts) | |
778 | (let ((doc (opt-documentation o))) | |
779 | (cond ((not o)) | |
780 | ((not (opt-long-name o)) | |
781 | (when newlinep | |
782 | (terpri stream) | |
783 | (setf newlinep nil)) | |
784 | (pprint-logical-block (stream nil) | |
785 | (print-text doc stream)) | |
786 | (terpri stream)) | |
787 | (t | |
788 | (setf newlinep t) | |
789 | (pprint-logical-block (stream nil :prefix " ") | |
790 | (pprint-indent :block 30 stream) | |
791 | (format stream "~:[ ~;-~:*~C,~] --~A" | |
792 | (opt-short-name o) | |
793 | (opt-long-name o)) | |
794 | (when (opt-arg-name o) | |
795 | (format stream "~:[=~A~;[=~A]~]" | |
796 | (opt-arg-optional-p o) | |
797 | (opt-arg-name o))) | |
798 | (write-string " " stream) | |
799 | (pprint-tab :line 30 1 stream) | |
800 | (print-text doc stream)) | |
801 | (terpri stream))))))) | |
802 | ||
803 | (defun sanity-check-option-list (opts) | |
804 | "Check the option list OPTS for basic sanity. Reused short and long option | |
805 | names are diagnosed. Maybe other problems will be reported later. Returns a | |
806 | list of warning strings." | |
807 | (let ((problems nil) | |
808 | (longs (make-hash-table :test #'equal)) | |
809 | (shorts (make-hash-table))) | |
810 | (flet ((problem (msg &rest args) | |
811 | (push (apply #'format nil msg args) problems))) | |
812 | (dolist (o opts) | |
813 | (push o (gethash (opt-long-name o) longs)) | |
814 | (push o (gethash (opt-short-name o) shorts))) | |
815 | (maphash (lambda (k v) | |
816 | (when (and k (cdr v)) | |
817 | (problem "Long name `--~A' reused in ~S" k v))) | |
818 | longs) | |
819 | (maphash (lambda (k v) | |
820 | (when (and k (cdr v)) | |
821 | (problem "Short name `-~C' reused in ~S" k v))) | |
822 | shorts) | |
823 | problems))) | |
824 | ||
825 | ;;;----- That's all, folks -------------------------------------------------- |