3 %%% Miscellaneous functionality
5 %%% (c) 2015 Straylight/Edgeware
8 %%%----- Licensing notice ---------------------------------------------------
10 %%% This file is part of the Sensible Object Design, an object system for C.
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.
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.
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.
26 \chapter{Miscellaneous functionality} \label{ch:misc}
28 %%%--------------------------------------------------------------------------
29 \section{Utilities} \label{sec:misc.utilities}
31 These symbols are defined in the @|sod-utilities| package.
34 {with-gensyms (@{ @<var> @! (@<var> @[@<name>@]) @}^*) \\ \ind
40 {once-only (@[[ :environment @<env> @]]
41 @{ @<var> @! (@<var> @[@<value-form>@]) @}^*) \\ \ind
47 {parse-body @<body> \&key :docp :declp
48 @> @<doc-string> @<declarations> @<body-forms>}
51 \begin{describe}{cls}{loc}
54 \begin{describe}{fun}{locp @<object> @> @<generalized-boolean>}
57 \begin{describe}{mac}{locf @<place> @> @<locative>}
61 {\dhead{fun}{ref @<locative> @> @<value>}
62 \dhead{fun}{setf (ref @<locative>) @<value>}}
67 @{ @<var> @! (@{ @<var> @!
68 (@<var> @[@<locative>@]) @}^*) @} \\ \ind
73 \begin{describe}{sym}{it}
76 \begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@]}
79 \begin{describe}{mac}{awhen @<condition> @<form>^*}
82 \begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^*}
87 {acase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
89 {aecase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
90 \dhead{mac}{atypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}
91 \dhead{mac}{aetypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}}
94 \begin{describe}{mac}{asetf @{ @<place> @<value> @}^*}
97 \begin{describe}{gf}{instance-initargs @<instance>}
101 {\dhead{fun}{copy-instance @<instance> \&rest @<initargs>}
102 \dhead{gf}{copy-instance-using-class @<class> @<instance>
107 {\dhead{gf}{generic-function-methods @<generic-function> @> @<list>}
108 \dhead{gf}{method-specializers @<method> @> @<list>}
109 \dhead{cls}{eql-specializer}
110 \dhead{gf}{eql-specializer-object @<specializer> @> @<value>}}
113 \begin{describe}{fun}{make-list-builder \&optional @<initial> @> @<builder>}
116 \begin{describe}{fun}{lbuild-add @<builder> @<item> @> @<builder>}
119 \begin{describe}{fun}{lbuild-add-list @<builder> @<list> @> @<builder>}
122 \begin{describe}{fun}{lbuild-list @<builder> @> @<list>}
125 \begin{describe}{fun}
126 {mappend @<function> @<list> \&rest @<more-lists> @> @<result-list>}
129 \begin{describe}{cls}{inconsistent-merge-error (error) \&key :candidates}
132 \begin{describe}{gf}{merge-error-candidates @<error> @> @<list>}
135 \begin{describe}{fun}
136 {merge-lists @<lists> \&key :pick (:test \#'eql) @> @<list>}
139 \begin{describe}{mac}
140 {categorize (\=@<item-var> @<items>
141 @[[ :bind (@{ @<var> @! (@<var> @[@<value>@]) @}^*) @]])
143 (@{ (@<cat-var> @<cat-predicate>) @}^*) \- \\
149 \begin{describe}{fun}
150 {frob-identifier @<string> \&key :swap-case :swap-hyphen
151 @> @<frobbed-string>}
154 \begin{describe}{fun}{whitespace-char-p @<character> @> @<generic-function>}
157 \begin{describe}{fun}
158 {update-position @<character> @<line> @<column>
159 @> @<new-line> @<new-column>}
162 \begin{describe}{fun}
163 {backtrack-position @<character> @<line> @<column>
164 @> @<old-line> @<old-column>}
167 \begin{describe}{fun}
168 {compose @<function> \&rest @<more-functions> @> @<function>}
171 \begin{describe}{fun}{symbolicate \&rest @<symbols> @> @<symbol>}
174 \begin{describe}{mac}
175 {maybe-print-unreadable-object (@<object> @<stream>
177 :identity @<identity> @]]) \\ \ind
182 \begin{describe}{fun}{print-ugly-stuff @<stream> @<func> @> @<value>^*}
185 \begin{describe}{mac}
186 {dosequence (@<var> @<sequence>
187 @[[ :start @<start> @! :end @<end> @!
188 :indexvar @<var> @]]) \\ \ind
190 @{ @<tag> @! @<statement> @}^*}
193 \begin{describe}{mac}
194 {define-access-wrapper @<from> @<to>
195 @[[ :read-only @<read-only-flag> @]]}
198 \begin{describe}{mac}
199 {default-slot (@<instance> @<slot> @[@<slot-names>@]) \\ \ind
203 \begin{describe}{mac}
204 {define-on-demand-slot @<class> @<slot> (@<instance>) \\ \ind
205 @[[ @<declaration>^* @! @<doc-string> @]] \\
209 %%%--------------------------------------------------------------------------
210 \section{Condition utilities} \label{sec:misc.condition}
212 These symbols are defined in the @|sod-parser| package.
214 \begin{describe}{cls}{enclosing-condition (condition) \&key :condition}
218 {enclosed-condition @<enclosing-condition> @> @<condition>}
221 \begin{describe}{fun}{cerror* @<datum> \&rest @<arguments>}
224 %%%--------------------------------------------------------------------------
225 \section{Option parser} \label{sec:misc.optparse}
227 These symbols are defined in the @!optparse| package.
229 \begin{describe}{fun}{exit \&optional (@<code> 0) \&key :abrupt}
232 \begin{describe}{var}{*program-name*}
235 \begin{describe}{var}{*command-line*}
238 \begin{describe}{fun}{set-command-line-arguments}
241 \begin{describe}{fun}{moan @<format-string> \&rest @<format-args>}
244 \begin{describe}{fun}{die @<format-string> \&rest @<format-args>}
247 \begin{describe}{var}{*options*}
250 \begin{describe}{cls}{option}
253 \begin{describe}{fun}{optionp @<object> @> @<generalized-boolean>}
256 \begin{describe}{fun}
257 {make-option \=@<long-name> @<short-name> \+ \\
258 \&optional @<arg-name> \\
259 \&key :tag :negated-tag :arg-optional-p :documentation \-
264 {\dhead{fun}{opt-short-name @<option> @> @<character-or-null>}
265 \dhead{fun}{setf (opt-short-name @<option>) @<character-or-null>}
266 \dhead{fun}{opt-long-name @<option> @> @<string-or-null>}
267 \dhead{fun}{setf (opt-long-name @<option>) @<string-or-null>}
268 \dhead{fun}{opt-tag @<option> @> @<tag>}
269 \dhead{fun}{setf (opt-tag @<option>) @<tag>}
270 \dhead{fun}{opt-negated-tag @<option> @> @<tag>}
271 \dhead{fun}{setf (opt-negated-tag @<option>) @<tag>}
272 \dhead{fun}{opt-arg-name @<option> @> @<string-or-null>}
273 \dhead{fun}{setf (opt-arg-name @<option>) @<string-or-null>}
274 \dhead{fun}{opt-optional-p @<option> @> @<generalized-boolean>}
275 \dhead{fun}{setf (opt-optional-p @<option>) @<generalized-boolean>}
276 \dhead{fun}{opt-documentation @<option> @> @<string-or-null>}
277 \dhead{fun}{setf (opt-documentation @<option>) @<string-or-null>}}
280 \begin{describe}{cls}{option-parser}
283 \begin{describe}{fun}{option-parser-p @<object> @> @<generalized-boolean>}
286 \begin{describe}{fun}
287 {make-option-parser \&key \=:args :options :non-option :numericp \+ \\
288 :negated-numeric-p long-only-p \-
289 \nlret @<option-parser>}
293 {\dhead{fun}{op-options @<option-parser> @> @<list>}
294 \dhead{fun}{setf (op-options @<option-parser>) @<list>}
295 \dhead{fun}{op-non-option @<option-parser> @> @<action>}
296 \dhead{fun}{setf (op-non-option @<option-parser>) @<action>}
297 \dhead{fun}{op-long-only-p @<option-parser> @> @<generalized-boolean>}
298 \dhead{fun}{setf (op-long-only-p @<option-parser>) @<generalized-boolean>}
299 \dhead{fun}{op-numeric-p @<option-parser> @> @<generalized-boolean>}
300 \dhead{fun}{setf (op-numeric-p @<option-parser>) @<generalized-boolean>}
301 \dhead{fun}{op-negated-numeric-p @<option-parser> @<generalized-boolean>}
302 \dhead{fun}{setf (op-negated-numeric-p @<option-parser>) @<generalized-boolean>}
303 \dhead{fun}{op-negated-p @<option-parser> @> @<generalized-boolean>}
304 \dhead{fun}{setf (op-negated-p @<option-parser>) @<generalized-boolean>}}
307 \begin{describe}{cls}
308 {option-parse-error (error simple-condition)
309 \&key :format-control :format-arguments}
312 \begin{describe}{fun}{option-parse-remainder @<option-parser>}
315 \begin{describe}{fun}{option-parse-return @<tag> \&optional @<argument>}
318 \begin{describe}{fun}{option-parse-next @<option-parser>}
321 \begin{describe}{mac}{option-parse-try @<form>^*}
324 \begin{describe}{mac}{with-unix-error-reporting () @<form>^*}
327 \begin{describe}{mac}
328 {defopthandler @<name> (@<var> @[@<arg>@]) @<lambda-list> \\ \ind
329 @[[ @<declaration>^* @! @<doc-string> @]] \\
333 \begin{describe}{fun}
334 {invoke-option-handler @<handler> @<locative> @<arg> @<arguments>}
337 \begin{describe}{opt}{set \&optional @<value>}
340 \begin{describe}{opt}{clear \&optional @<value>}
343 \begin{describe}{opt}{inc \&optional @<maximum> @<step>}
346 \begin{describe}{opt}{dec \&optional <minimum> <step>}
349 \begin{describe}{opt}{read}
352 \begin{describe}{opt}{int \&key :radix :min :max}
355 \begin{describe}{opt}{string}
358 \begin{describe}{opt}{keyword \&optional @<valid>}
361 \begin{describe}{opt}{list \&optional @<handler> \&rest @<handler-args>}
364 \begin{describe}{mac}
365 {defoptmacro @<name> @<lambda-list> \\ \ind
366 @[[ @<declaration>^* @! @<doc-string> @]] \\
370 \begin{describe}{fun}{parse-option-form @<form>}
373 \begin{describe}{mac}
374 {options @{ \=@<string> @! \+ \\
375 @<option-macro> @! (@<option-macro> @<macro-arg>^*) @! \\
376 (@[[ \=@<character> @! (:short-name @<character>) @! \+ \\
377 @<string>^* @! @<symbol> @! @<rational> @!
378 (:long-name @<string>) @! \\
379 (@<string> @<format-arg>^+) @!
380 (:doc @<string> @<format-arg>^*) @! \\
381 (:arg @<arg-name>) @! (:opt-arg @<arg-name>) @! \\
382 @<keyword> @! (:tag @<tag>) @!
383 (:negated-tag @<tag>) @! \\
384 @{ (@<handler> @<var> @<handler-arg>^*) @}^*
388 \begin{describe}{fun}
389 {simple-usage @<option-list> \&optional @<mandatory-args> @> @<list>}
392 \begin{describe}{fun}{show-usage @<prog> @<usage> \&optional @<stream>}
395 \begin{describe}{fun}
396 {show-help @<prog> @<usage> @<option-list> \&optional @<stream>}
399 \begin{describe}{fun}{sanity-check-option-list @<option-list>}
404 \dhead{var}{*version*}
405 \dhead{var}{*usage*}}
408 \begin{describe}{fun}{do-usage \&optional @<stream>}
411 \begin{describe}{fun}{die-usage}
414 \begin{describe}{optmac}
415 {help-options \&key :short-help :short-version :short-usage}
418 \begin{describe}{fun}
419 {define-program \&key \=:program-name \+ \\
420 :help :version :usage :full-usage \\
424 \begin{describe}{mac}
425 {do-options (@[[ :parser @<option-parser> @]]) \\ \ind
426 @{ (@{ @<case> @! (@<case>^*)@} (@[@[@<opt-var>@] @<arg-var>@])
430 %%%--------------------------------------------------------------------------
431 \section{Property sets} \label{sec:misc.pset}
433 \begin{describe}{fun}{property-key @<name> @> @<keyword>}
436 \begin{describe}{gf}{decode-property @<raw-value> @> @<type> @<value>}
439 \begin{describe}{cls}{property}
442 \begin{describe}{fun}{propertyp @<object> @> @<generalized-boolean>}
445 \begin{describe}{fun}
446 {make-property @<name> @<raw-value> \&key :type :location :seenp}
450 {\dhead{fun}{p-name @<property> @> @<name>}
451 \dhead{fun}{p-value @<property> @> @<value>}
452 \dhead{fun}{p-type @<property> @> @<type>}
453 \dhead{fun}{p-key @<property> @> @<symbol>}
454 \dhead{fun}{p-seenp @<property> @> @<boolean>}
455 \dhead{fun}{setf (p-seenp @<property>) @<boolean>}}
458 \begin{describe}{gf}{decode-property @<raw-value> @> @<type> @<value>}
462 {coerce-property-value @<value> @<type> @<wanted> @> @<coerced-value>}
465 \begin{describe}{cls}{pset}
468 \begin{describe}{fun}{psetp @<object> @> @<generalized-boolean>}
471 \begin{describe}{fun}{make-pset @> @<pset>}
474 \begin{describe}{fun}{pset-get @<pset> @<key> @> @<property-or-nil>}
477 \begin{describe}{fun}{pset-store @<pset> @<property> @> @<property>}
480 \begin{describe}{fun}{pset-map @<func> @<pset>}
483 \begin{describe}{mac}
484 {with-pset-iterator (@<iter> @<pset>) @<declaration>^* @<form>^*}
487 \begin{describe}{fun}
488 {store-property @<pset> @<name> @<value> \&key :type :location
492 \begin{describe}{fun}
493 {get-property @<pset> @<name> @<type> \&optional @<default>
494 @> @<value> @<floc-or-nil>}
497 \begin{describe}{fun}
498 {add-property @<pset> @<name> @<value> \&key :type :location
502 \begin{describe}{fun}{make-property-set \&rest @<plist> @> @<pset>}
505 \begin{describe}{gf}{property-set @<thing> @> @<pset>}
508 \begin{describe}{fun}{check-unused-properties @<pset>}
511 \begin{describe}{mac}
512 {default-slot-from-property
513 (@<instance> @<slot> @[@<slot-names>@]) \\ \ind\ind
514 (@<pset> @<property> @<type> @[@<prop-var> @<convert-form>^*@]) \- \\
519 \begin{describe}{fun}
520 {parse-property-set @<scanner>
521 @> @<result> @<success-flag> @<consumed-flag>}
524 %%%--------------------------------------------------------------------------
525 \section{Miscellaneous translator features} \label{sec:misc.pset}
527 \begin{describe}{var}{*sod-version*}
530 \begin{describe}{var}{*debugout-pathname*}
533 \begin{describe}{fun}{test-module @<path> @<reason>}
536 \begin{describe}{fun}
537 {test-parse-c-type @<string>
538 @> t @<c-type> @<kernel> @<string> @! nil @<indicator>}
541 \begin{describe}{mac}
542 {test-parser (@<scanner>) @<parser> @<input>
543 @> @<success-flag> @<result> @<remainder>}
546 \begin{describe}{fun}{exercise}
549 \begin{describe}{fun}{sod-frontend:main}
552 %%%----- That's all, folks --------------------------------------------------
556 %%% TeX-master: "sod.tex"