chiark / gitweb /
doc/: Some minor tweaks and corrections.
[sod] / doc / misc.tex
1 %%% -*-latex-*-
2 %%%
3 %%% Miscellaneous functionality
4 %%%
5 %%% (c) 2015 Straylight/Edgeware
6 %%%
7
8 %%%----- Licensing notice ---------------------------------------------------
9 %%%
10 %%% This file is part of the Sensible Object Design, an object system for C.
11 %%%
12 %%% SOD 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 %%% SOD 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 SOD; if not, write to the Free Software Foundation,
24 %%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25
26 \chapter{Miscellaneous functionality} \label{ch:misc}
27
28 %%%--------------------------------------------------------------------------
29 \section{Utilities} \label{sec:misc.utilities}
30
31 These symbols are defined in the @|sod-utilities| package.
32
33 \begin{describe}{mac}
34     {with-gensyms (@{ @<var> @! (@<var> @[@<name>@]) @}^*)      \\ \ind
35       @<declaration>^*                                          \\
36       @<form>^*}
37 \end{describe}
38
39 \begin{describe}{mac}
40     {once-only (@[[ :environment @<env> @]]
41                 @{ @<var> @! (@<var> @[@<value-form>@]) @}^*)   \\ \ind
42       @<declaration>^*                                          \\
43       @<form>^*}
44 \end{describe}
45
46 \begin{describe}{mac}
47     {parse-body @<body> \&key :docp :declp
48       @> @<doc-string> @<declarations> @<body-forms>}
49 \end{describe}
50
51 \begin{describe}{cls}{loc}
52 \end{describe}
53
54 \begin{describe}{fun}{locp @<object> @> @<generalized-boolean>}
55 \end{describe}
56
57 \begin{describe}{mac}{locf @<place> @> @<locative>}
58 \end{describe}
59
60 \begin{describe*}
61     {\dhead{fun}{ref @<locative> @> @<value>}
62      \dhead{fun}{setf (ref @<locative>) @<value>}}
63 \end{describe*}
64
65 \begin{describe}{mac}
66     {with-locatives
67         @{ @<var> @! (@{ @<var> @!
68                          (@<var> @[@<locative>@]) @}^*) @}      \\ \ind
69       @<declaration>^*                                          \\
70       @<form>^*}
71 \end{describe}
72
73 \begin{describe}{sym}{it}
74 \end{describe}
75
76 \begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@]}
77 \end{describe}
78
79 \begin{describe}{mac}{aand @<form>^*}
80 \end{describe}
81
82 \begin{describe}{mac}{awhen @<condition> @<form>^*}
83 \end{describe}
84
85 \begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^*}
86 \end{describe}
87
88 \begin{describe*}
89     {\dhead{mac}
90       {acase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
91      \dhead{mac}
92       {aecase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
93      \dhead{mac}{atypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}
94      \dhead{mac}{aetypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}}
95 \end{describe*}
96
97 \begin{describe}{mac}{asetf @{ @<place> @<value> @}^*}
98 \end{describe}
99
100 \begin{describe}{gf}{instance-initargs @<instance>}
101 \end{describe}
102
103 \begin{describe*}
104     {\dhead{fun}{copy-instance @<instance> \&rest @<initargs>}
105      \dhead{gf}{copy-instance-using-class @<class> @<instance>
106                                           \&rest @<initargs>}}
107 \end{describe*}
108
109 \begin{describe*}
110     {\dhead{gf}{generic-function-methods @<generic-function> @> @<list>}
111      \dhead{gf}{method-specializers @<method> @> @<list>}
112      \dhead{cls}{eql-specializer}
113      \dhead{gf}{eql-specializer-object @<specializer> @> @<value>}}
114 \end{describe*}
115
116 \begin{describe}{fun}{make-list-builder \&optional @<initial> @> @<builder>}
117 \end{describe}
118
119 \begin{describe}{fun}{lbuild-add @<builder> @<item> @> @<builder>}
120 \end{describe}
121
122 \begin{describe}{fun}{lbuild-add-list @<builder> @<list> @> @<builder>}
123 \end{describe}
124
125 \begin{describe}{fun}{lbuild-list @<builder> @> @<list>}
126 \end{describe}
127
128 \begin{describe}{fun}
129     {mappend @<function> @<list> \&rest @<more-lists> @> @<result-list>}
130 \end{describe}
131
132 \begin{describe}{fun}
133     {distinguished-point-shortest-paths @<root> @<neighbours-func>
134       @> @<list>}
135 \end{describe}
136
137 \begin{describe}{cls}{inconsistent-merge-error (error) \&key :candidates}
138 \end{describe}
139
140 \begin{describe}{gf}{merge-error-candidates @<error> @> @<list>}
141 \end{describe}
142
143 \begin{describe}{fun}
144     {merge-lists @<lists> \&key :pick (:test \#'eql) :present @> @<list>}
145 \end{describe}
146
147 \begin{describe}{mac}
148     {categorize (\=@<item-var> @<items>
149                    @[[ :bind (@{ @<var> @!
150                                  (@<var> @[@<value>@]) @}^*) @]])
151                                                                 \\ \ind\ind
152         (@{ (@<cat-var> @<cat-predicate>) @}^*)               \-\\
153       @<declaration>^*                                          \\
154       @<form>^*
155      \-\nlret @<value>^*}
156 \end{describe}
157
158 \begin{describe}{fun}{partial-order-minima @<items> @<order> @> @<list>}
159 \end{describe}
160
161 \begin{describe}{fun}
162     {frob-identifier @<string> \&key :swap-case :swap-hyphen
163       @> @<frobbed-string>}
164 \end{describe}
165
166 \begin{describe}{fun}{whitespace-char-p @<character> @> @<generic-function>}
167 \end{describe}
168
169 \begin{describe}{fun}
170     {update-position @<character> @<line> @<column>
171       @> @<new-line> @<new-column>}
172 \end{describe}
173
174 \begin{describe}{fun}
175     {backtrack-position @<character> @<line> @<column>
176       @> @<old-line> @<old-column>}
177 \end{describe}
178
179 \begin{describe}{fun}
180     {compose @<function> \&rest @<more-functions> @> @<function>}
181 \end{describe}
182
183 \begin{describe}{mac}{defvar @<name> @<documentation> @> @<name>}
184 \end{describe}
185
186 \begin{describe}{fun}{symbolicate \&rest @<symbols> @> @<symbol>}
187 \end{describe}
188
189 \begin{describe}{mac}
190     {maybe-print-unreadable-object
191         (@<object> @<stream>
192          @[[ :type @<type> @!
193              :identity @<identity> @]])                         \\ \ind
194       @<declaration>^*                                          \\
195       @<form>^*}
196 \end{describe}
197
198 \begin{describe}{fun}{print-ugly-stuff @<stream> @<func> @> @<value>^*}
199 \end{describe}
200
201 \begin{describe}{mac}
202     {dosequence (@<var> @<sequence>
203                  @[[ :start @<start> @! :end @<end> @!
204                      :indexvar @<var> @]])                      \\ \ind
205       @<declaration>^*                                          \\
206       @{ @<tag> @! @<statement> @}^*}
207 \end{describe}
208
209 \begin{describe}{mac}
210     {define-access-wrapper @<from> @<to>
211                            @[[ :read-only @<read-only-flag> @]]}
212 \end{describe}
213
214 \begin{describe}{cls}
215     {simple-control-error (control-error simple-error)
216         \&key :format-control :format-arguments}
217 \end{describe}
218
219 \begin{describe}{fun}
220     {designated-condition
221         \=@<default-type> @<datum> @<arguments>                 \\
222         \>\&key :allow-pointless-arguments
223       \nlret @<condition>}
224 \end{describe}
225
226 \begin{describe}{fun}
227     {invoke-associated-restart @<restart> @<condition> \&rest @<arguments>}
228 \end{describe}
229
230 \begin{describe}{mac}
231     {default-slot (@<instance> @<slot> @[@<slot-names>@])       \\ \ind
232       @<form>^*}
233 \end{describe}
234
235 \begin{describe}{mac}
236     {define-on-demand-slot @<class> @<slot> (@<instance>)       \\ \ind
237       @[[ @<declaration>^* @! @<doc-string> @]]                 \\
238       @<form>^*}
239 \end{describe}
240
241 %%%--------------------------------------------------------------------------
242 \section{Condition utilities} \label{sec:misc.condition}
243
244 These symbols are defined in the @|sod-parser| package.
245
246 \begin{describe}{cls}{enclosing-condition (condition) \&key :condition}
247 \end{describe}
248
249 \begin{describe}{gf}
250     {enclosed-condition @<enclosing-condition> @> @<condition>}
251 \end{describe}
252
253 \begin{describe}{cls}{information (condition) \&key}
254 \end{describe}
255
256 \begin{describe}{cls}
257     {simple-information (simple-condition information)          \\ \ind
258       \&key :format-control :format-arguments}
259 \end{describe}
260
261 \begin{describe}{fun}{info @<datum> \&rest @<arguments> @> @<flag>}
262 \end{describe}
263
264 \begin{describe*}
265     {\dhead{rst}{noted}
266      \dhead{fun}{noted \&optional @<condition>}}
267 \end{describe*}
268
269 \begin{describe}{fun}{cerror* @<datum> \&rest @<arguments>}
270 \end{describe}
271
272 %%%--------------------------------------------------------------------------
273 \section{Option parser} \label{sec:misc.optparse}
274
275 These symbols are defined in the @|optparse| package.
276
277 \begin{describe}{fun}{exit \&optional (@<code> 0) \&key :abrupt}
278 \end{describe}
279
280 \begin{describe}{var}{*program-name*}
281 \end{describe}
282
283 \begin{describe}{var}{*command-line*}
284 \end{describe}
285
286 \begin{describe}{fun}{set-command-line-arguments}
287 \end{describe}
288
289 \begin{describe}{fun}{moan @<format-string> \&rest @<format-args>}
290 \end{describe}
291
292 \begin{describe}{fun}{die @<format-string> \&rest @<format-args>}
293 \end{describe}
294
295 \begin{describe}{var}{*options*}
296 \end{describe}
297
298 \begin{describe}{cls}{option}
299 \end{describe}
300
301 \begin{describe}{fun}{optionp @<object> @> @<generalized-boolean>}
302 \end{describe}
303
304 \begin{describe}{fun}
305     {make-option \=@<long-name> @<short-name>                 \+\\
306                    \&optional @<arg-name>                       \\
307                    \&key :tag :negated-tag
308                          :arg-optional-p :documentation       \-
309       \nlret @<option>}
310 \end{describe}
311
312 \begin{describe*}
313     {\dhead{fun}{opt-short-name @<option> @> @<character-or-null>}
314      \dhead{fun}{setf (opt-short-name @<option>) @<character-or-null>}
315      \dhead{fun}{opt-long-name @<option> @> @<string-or-null>}
316      \dhead{fun}{setf (opt-long-name @<option>) @<string-or-null>}
317      \dhead{fun}{opt-tag @<option> @> @<tag>}
318      \dhead{fun}{setf (opt-tag @<option>) @<tag>}
319      \dhead{fun}{opt-negated-tag @<option> @> @<tag>}
320      \dhead{fun}{setf (opt-negated-tag @<option>) @<tag>}
321      \dhead{fun}{opt-arg-name @<option> @> @<string-or-null>}
322      \dhead{fun}{setf (opt-arg-name @<option>) @<string-or-null>}
323      \dhead{fun}{opt-optional-p @<option> @> @<generalized-boolean>}
324      \dhead{fun}{setf (opt-optional-p @<option>) @<generalized-boolean>}
325      \dhead{fun}{opt-documentation @<option> @> @<string-or-null>}
326      \dhead{fun}{setf (opt-documentation @<option>) @<string-or-null>}}
327 \end{describe*}
328
329 \begin{describe}{cls}{option-parser}
330 \end{describe}
331
332 \begin{describe}{fun}{option-parser-p @<object> @> @<generalized-boolean>}
333 \end{describe}
334
335 \begin{describe}{fun}
336     {make-option-parser \&key \=:args :options :non-option :numericp \+ \\
337                               :negated-numeric-p long-only-p \-
338       \nlret @<option-parser>}
339 \end{describe}
340
341 \begin{describe*}
342     {\dhead{fun}{op-options @<option-parser> @> @<list>}
343      \dhead{fun}{setf (op-options @<option-parser>) @<list>}
344      \dhead{fun}{op-non-option @<option-parser> @> @<action>}
345      \dhead{fun}{setf (op-non-option @<option-parser>) @<action>}
346      \dhead{fun}{op-long-only-p @<option-parser> @> @<generalized-boolean>}
347      \dhead{fun}{setf (op-long-only-p @<option-parser>) @<generalized-boolean>}
348      \dhead{fun}{op-numeric-p @<option-parser> @> @<generalized-boolean>}
349      \dhead{fun}{setf (op-numeric-p @<option-parser>) @<generalized-boolean>}
350      \dhead{fun}{op-negated-numeric-p @<option-parser> @<generalized-boolean>}
351      \dhead{fun}{setf (op-negated-numeric-p @<option-parser>) @<generalized-boolean>}
352      \dhead{fun}{op-negated-p @<option-parser> @> @<generalized-boolean>}
353      \dhead{fun}{setf (op-negated-p @<option-parser>) @<generalized-boolean>}}
354 \end{describe*}
355
356 \begin{describe}{cls}
357     {option-parse-error (error simple-condition)
358       \&key :format-control :format-arguments}
359 \end{describe}
360
361 \begin{describe}{fun}{option-parse-remainder @<option-parser>}
362 \end{describe}
363
364 \begin{describe}{fun}{option-parse-return @<tag> \&optional @<argument>}
365 \end{describe}
366
367 \begin{describe}{fun}{option-parse-next @<option-parser>}
368 \end{describe}
369
370 \begin{describe}{mac}{option-parse-try @<form>^*}
371 \end{describe}
372
373 \begin{describe}{mac}{with-unix-error-reporting () @<form>^*}
374 \end{describe}
375
376 \begin{describe}{mac}
377     {defopthandler @<name> (@<var> @[@<arg>@]) @<lambda-list> \\ \ind
378       @[[ @<declaration>^* @! @<doc-string> @]] \\
379       @<form>^*}
380 \end{describe}
381
382 \begin{describe}{fun}
383     {invoke-option-handler @<handler> @<locative> @<arg> @<arguments>}
384 \end{describe}
385
386 \begin{describe}{opt}{set \&optional @<value>}
387 \end{describe}
388
389 \begin{describe}{opt}{clear \&optional @<value>}
390 \end{describe}
391
392 \begin{describe}{opt}{inc \&optional @<maximum> @<step>}
393 \end{describe}
394
395 \begin{describe}{opt}{dec \&optional <minimum> <step>}
396 \end{describe}
397
398 \begin{describe}{opt}{read}
399 \end{describe}
400
401 \begin{describe}{opt}{int \&key :radix :min :max}
402 \end{describe}
403
404 \begin{describe}{opt}{string}
405 \end{describe}
406
407 \begin{describe}{opt}{keyword \&optional @<valid>}
408 \end{describe}
409
410 \begin{describe}{opt}{list \&optional @<handler> \&rest @<handler-args>}
411 \end{describe}
412
413 \begin{describe}{mac}
414     {defoptmacro @<name> @<lambda-list> \\ \ind
415       @[[ @<declaration>^* @! @<doc-string> @]] \\
416       @<form>^*}
417 \end{describe}
418
419 \begin{describe}{fun}{parse-option-form @<form>}
420 \end{describe}
421
422 \begin{describe}{mac}
423     {options @{ \=@<string> @! \+ \\
424                   @<option-macro> @! (@<option-macro> @<macro-arg>^*) @! \\
425                   (@[[ \=@<character> @! (:short-name @<character>) @! \+ \\
426                          @<string>^* @! @<symbol> @! @<rational> @!
427                          (:long-name @<string>) @! \\
428                          (@<string> @<format-arg>^+) @!
429                          (:doc @<string> @<format-arg>^*) @! \\
430                          (:arg @<arg-name>) @! (:opt-arg @<arg-name>) @! \\
431                          @<keyword> @! (:tag @<tag>) @!
432                                        (:negated-tag @<tag>) @! \\
433                          @{ (@<handler> @<var> @<handler-arg>^*) @}^*
434                    @]]) @}^*}
435 \end{describe}
436
437 \begin{describe}{fun}
438     {simple-usage @<option-list> \&optional @<mandatory-args> @> @<list>}
439 \end{describe}
440
441 \begin{describe}{fun}{show-usage @<prog> @<usage> \&optional @<stream>}
442 \end{describe}
443
444 \begin{describe}{fun}
445     {show-help @<prog> @<usage> @<option-list> \&optional @<stream>}
446 \end{describe}
447
448 \begin{describe}{fun}{sanity-check-option-list @<option-list>}
449 \end{describe}
450
451 \begin{describe*}
452     {\dhead{var}{*help*}
453      \dhead{var}{*version*}
454      \dhead{var}{*usage*}}
455 \end{describe*}
456
457 \begin{describe}{fun}{do-usage \&optional @<stream>}
458 \end{describe}
459
460 \begin{describe}{fun}{die-usage}
461 \end{describe}
462
463 \begin{describe}{optmac}
464     {help-options \&key :short-help :short-version :short-usage}
465 \end{describe}
466
467 \begin{describe}{fun}
468     {define-program \&key \=:program-name \+ \\
469                             :help :version :usage :full-usage \\
470                             :options}
471 \end{describe}
472
473 \begin{describe}{mac}
474     {do-options (@[[ :parser @<option-parser> @]]) \\ \ind
475       @{ (@{ @<case> @! (@<case>^*)@} (@[@[@<opt-var>@] @<arg-var>@])
476           @<form>^*) @}^*}
477 \end{describe}
478
479 %%%--------------------------------------------------------------------------
480 \section{Property sets} \label{sec:misc.pset}
481
482 \begin{describe}{fun}{property-key @<name> @> @<keyword>}
483 \end{describe}
484
485 \begin{describe}{gf}{decode-property @<raw-value> @> @<type> @<value>}
486 \end{describe}
487
488 \begin{describe}{cls}{property}
489 \end{describe}
490
491 \begin{describe}{fun}{propertyp @<object> @> @<generalized-boolean>}
492 \end{describe}
493
494 \begin{describe}{fun}
495     {make-property @<name> @<raw-value> \&key :type :location :seenp}
496 \end{describe}
497
498 \begin{describe*}
499     {\dhead{fun}{p-name @<property> @> @<name>}
500      \dhead{fun}{p-value @<property> @> @<value>}
501      \dhead{fun}{p-type @<property> @> @<type>}
502      \dhead{fun}{p-key @<property> @> @<symbol>}
503      \dhead{fun}{p-seenp @<property> @> @<boolean>}
504      \dhead{fun}{setf (p-seenp @<property>) @<boolean>}}
505 \end{describe*}
506
507 \begin{describe}{gf}{decode-property @<raw-value> @> @<type> @<value>}
508 \end{describe}
509
510 \begin{describe}{gf}
511     {coerce-property-value @<value> @<type> @<wanted> @> @<coerced-value>}
512 \end{describe}
513
514 \begin{describe}{cls}{pset}
515 \end{describe}
516
517 \begin{describe}{fun}{psetp @<object> @> @<generalized-boolean>}
518 \end{describe}
519
520 \begin{describe}{fun}{make-pset @> @<pset>}
521 \end{describe}
522
523 \begin{describe}{fun}{pset-get @<pset> @<key> @> @<property-or-nil>}
524 \end{describe}
525
526 \begin{describe}{fun}{pset-store @<pset> @<property> @> @<property>}
527 \end{describe}
528
529 \begin{describe}{fun}{pset-map @<func> @<pset>}
530 \end{describe}
531
532 \begin{describe}{mac}
533     {with-pset-iterator (@<iter> @<pset>) @<declaration>^* @<form>^*}
534 \end{describe}
535
536 \begin{describe}{fun}
537     {store-property @<pset> @<name> @<value> \&key :type :location
538       @> @<property>}
539 \end{describe}
540
541 \begin{describe}{fun}
542     {get-property @<pset> @<name> @<type> \&optional @<default>
543       @> @<value> @<floc-or-nil>}
544 \end{describe}
545
546 \begin{describe}{fun}
547     {add-property @<pset> @<name> @<value> \&key :type :location
548       @> @<property>}
549 \end{describe}
550
551 \begin{describe}{fun}{make-property-set \&rest @<plist> @> @<pset>}
552 \end{describe}
553
554 \begin{describe}{gf}{property-set @<thing> @> @<pset>}
555 \end{describe}
556
557 \begin{describe}{fun}{check-unused-properties @<pset>}
558 \end{describe}
559
560 \begin{describe}{mac}
561     {default-slot-from-property
562         (@<instance> @<slot> @[@<slot-names>@]) \\ \ind\ind
563         (@<pset> @<property> @<type> @[@<prop-var> @<convert-form>^*@]) \- \\
564       @<declaration>^* \\
565       @<default-form>^*}
566 \end{describe}
567
568 \begin{describe}{fun}
569     {parse-property @<scanner> @<pset>
570       @> @<result> @<success-flag> @<consumed-flag>}
571 \end{describe}
572
573 \begin{describe}{fun}
574     {parse-property-set @<scanner>
575       @> @<result> @<success-flag> @<consumed-flag>}
576 \end{describe}
577
578 %%%--------------------------------------------------------------------------
579 \section{Miscellaneous translator features} \label{sec:misc.pset}
580
581 \begin{describe}{var}{*sod-version*}
582 \end{describe}
583
584 \begin{describe}{var}{*debugout-pathname*}
585 \end{describe}
586
587 \begin{describe}{fun}
588     {test-module @<path> \&key :reason :clear :backtrace @> @<status>}
589 \end{describe}
590
591 \begin{describe}{fun}
592     {test-parse-c-type @<string>
593       @> t @<c-type> @<kernel> @<string> @! nil @<indicator>}
594 \end{describe}
595
596 \begin{describe}{mac}
597     {test-parser (@<scanner> \&key :backtrace) @<parser> @<input>
598       @> @<result> @<status> @<remainder>}
599 \end{describe}
600
601 \begin{describe}{fun}{exercise}
602 \end{describe}
603
604 \begin{describe}{fun}{sod-frontend:main}
605 \end{describe}
606
607 %%%----- That's all, folks --------------------------------------------------
608
609 %%% Local variables:
610 %%% mode: LaTeX
611 %%% TeX-master: "sod.tex"
612 %%% TeX-PDF-mode: t
613 %%% End: