chiark - git - mdw - sod/blob - 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 Sensble 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       @<body-form>^*}
  36 \end{describe}
  37
  38 \begin{describe}{mac}
  39     {once-only (@[[ :environment @<env> @]]
  40                 @{ @<var> @! (@<var> @[@<value-form>@]) @}^*) \\ \ind
  41       @<body-form>^*}
  42 \end{describe}
  43
  44 \begin{describe}{mac}
  45     {parse-body @<body> @> @<doc-string> @<declarations> @<body-forms>}
  46 \end{describe}
  47
  48 \begin{describe}{cls}{loc}
  49 \end{describe}
  50
  51 \begin{describe}{fun}{locp @<object> @> @<generalized-boolean>}
  52 \end{describe}
  53
  54 \begin{describe}{macro}{locf @<place> @> @<locative>}
  55 \end{describe}
  56
  57 \begin{describe*}
  58     {\dhead{fun}{ref @<locative> @> @<value>}
  59      \dhead{fun}{setf (ref @<locative>) @<value>}}
  60 \end{describe*}
  61
  62 \begin{describe}{mac}
  63     {with-locatives
  64         @{ @<var> @! (@{ @<var> @!
  65                          (@<var> @[@<locative>@]) @}^*) @} \\ \ind
  66       @<body-form>^*}
  67 \end{describe}
  68
  69 \begin{describe}{sym}{it}
  70 \end{describe}
  71
  72 \begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@]}
  73 \end{describe}
  74
  75 \begin{describe}{mac}{awhen @<condition> @<body-form>^*}
  76 \end{describe}
  77
  78 \begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^*}
  79 \end{describe}
  80
  81 \begin{describe*}
  82     {\dhead{mac}
  83       {acase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
  84      \dhead{mac}
  85       {aecase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
  86      \dhead{mac}{atypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}
  87      \dhead{mac}{aetypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}}
  88 \end{describe*}
  89
  90 \begin{describe}{mac}{asetf @{ @<place> @<value> @}^*}
  91 \end{describe}
  92
  93 \begin{describe}{gf}{instance-initargs @<instance>}
  94 \end{describe}
  95
  96 \begin{describe*}
  97     {\dhead{fun}{copy-instance @<instance> \&rest @<initargs>}
  98      \dhead{gf}{copy-instance-using-class @<class> @<instance>
  99                                           \&rest @<initargs>}}
 100 \end{describe*}
 101
 102 \begin{describe*}
 103     {\dhead{gf}{generic-function-methods @<generic-function> @> @<list>}
 104      \dhead{gf}{method-specializers @<method> @> @<list>}
 105      \dhead{cls}{eql-specializer}
 106      \dhead{gf}{eql-specializer-object @<specializer> @> @<value>}}
 107 \end{describe*}
 108
 109 \begin{describe}{fun}{make-list-builder \&optional @<initial> @> @<builder>}
 110 \end{describe}
 111
 112 \begin{describe}{fun}{lbuild-add @<builder> @<item> @> @<builder>}
 113 \end{describe}
 114
 115 \begin{describe}{fun}{lbuild-add-list @<builder> @<list> @> @<builder>}
 116 \end{describe}
 117
 118 \begin{describe}{fun}{lbuild-list @<builder> @> @<list>}
 119 \end{describe}
 120
 121 \begin{describe}{fun}
 122     {mappend @<function> @<list> \&rest @<more-lists> @> @<result-list>}
 123 \end{describe}
 124
 125 \begin{describe}{cls}{inconsistent-merge-error (error) \&key :candidates}
 126 \end{describe}
 127
 128 \begin{describe}{gf}{merge-error-candidates @<error> @> @<list>}
 129 \end{describe}
 130
 131 \begin{describe}{fun}
 132     {merge-lists @<lists> \&key :pick (:test \#'eql) @> @<list>}
 133 \end{describe}
 134
 135 \begin{describe}{mac}
 136     {categorize (\=@<item-var> @<items>
 137                    @[[ :bind (@{ @<var> @! (@<var> @[@<value>@]) @}^*) @]])
 138                                                                  \\ \ind\ind
 139         (@{ @<cat-var> @<cat-predicate> @}^*) \- \\
 140       @<body-form>^* \-
 141      \nlret @<value>^*}
 142 \end{describe}
 143
 144 \begin{describe}{fun}
 145     {frob-identifier @<string> \&key :swap-case :swap-hyphen
 146       @> @<frobbed-string>}
 147 \end{describe}
 148
 149 \begin{describe}{fun}{whitespace-char-p @<character> @> @<generic-function>}
 150 \end{describe}
 151
 152 \begin{describe}{fun}
 153     {update-position @<character> @<line> @<column>
 154       @> @<new-line> @<new-column>}
 155 \end{describe}
 156
 157 \begin{describe}{fun}
 158     {backtrack-position @<character> @<line> @<column>
 159       @> @<old-line> @<old-column>}
 160 \end{describe}
 161
 162 \begin{describe}{fun}
 163     {compose @<function> \&rest @<more-functions> @> @<function>}
 164 \end{describe}
 165
 166 \begin{describe}{fun}{symbolicate \&rest @<symbols> @> @<symbol>}
 167 \end{describe}
 168
 169 \begin{describe}{mac}
 170     {maybe-print-unreadable-object (@<object> @<stream>
 171                                     @[[ :type @<type> @!
 172                                         :identity @<identity> @]]) \\ \ind
 173        @<body-form>^*}
 174 \end{describe}
 175
 176 \begin{describe}{mac}
 177     {dosequence (@<var> @<sequence>
 178                  @[[ :start @<start> @! :end @<end> @!
 179                      :indexvar @<var> @]]) \\ \ind
 180       @{ @<tag> @! @<body-form> @}^*}
 181 \end{describe}
 182
 183 \begin{describe}{mac}
 184     {define-access-wrapper @<from> @<to>
 185                            @[[ :read-only @<read-only-flag> @]]}
 186 \end{describe}
 187
 188 \begin{describe}{mac}
 189     {default-slot (@<instance> @<slot> @[@<slot-names>@]) \\ \ind
 190       @<body-form>^*}
 191 \end{describe}
 192
 193 \begin{describe}{mac}
 194     {define-on-demand-slot @<class> @<slot> (@<instance>) \\ \ind
 195       @<body-form>^*}
 196 \end{describe}
 197
 198 %%%--------------------------------------------------------------------------
 199 \section{Condition utilities} \label{sec:misc.condition}
 200
 201 These symbols are defined in the @|sod-parser| package.
 202
 203 \begin{describe}{cls}{enclosing-condition (condition) \&key :condition}
 204 \end{describe}
 205
 206 \begin{describe}{gf}
 207     {enclosed-condition @<enclosing-condition> @> @<condition>}
 208 \end{describe}
 209
 210 \begin{describe}{fun}{cerror* @<datum> \&rest @<arguments>}
 211 \end{describe}
 212
 213 %%%--------------------------------------------------------------------------
 214 \section{Option parser} \label{sec:misc.optparse}
 215
 216 These symbols are defined in the @!optparse| package.
 217
 218 \begin{describe}{fun}{exit \&optional (@<code> 0) \&key :abrupt}
 219 \end{describe}
 220
 221 \begin{describe}{var}{*program-name*}
 222 \end{describe}
 223
 224 \begin{describe}{var}{*command-line*}
 225 \end{describe}
 226
 227 \begin{describe}{fun}{set-command-line-arguments}
 228 \end{describe}
 229
 230 \begin{describe}{fun}{moan @<format-string> \&rest @<format-args>}
 231 \end{describe}
 232
 233 \begin{describe}{fun}{die @<format-string> \&rest @<format-args>}
 234 \end{describe}
 235
 236 \begin{describe}{var}{*options*}
 237 \end{describe}
 238
 239 \begin{describe}{cls}{option}
 240 \end{describe}
 241
 242 \begin{describe}{fun}{optionp @<object> @> @<generalized-boolean>}
 243 \end{describe}
 244
 245 \begin{describe}{fun}
 246     {make-option \=@<long-name> @<short-name> \+ \\
 247                    \&optional @<arg-name> \\
 248                    \&key :tag :negated-tag :arg-optional-p :documentation \-
 249       \nlret @<option>}
 250 \end{describe}
 251
 252 \begin{describe*}
 253     {\dhead{fun}{opt-short-name @<option> @> @<character-or-null>}
 254      \dhead{fun}{setf (opt-short-name @<option>) @<character-or-null>}
 255      \dhead{fun}{opt-long-name @<option> @> @<string-or-null>}
 256      \dhead{fun}{setf (opt-long-name @<option>) @<string-or-null>}
 257      \dhead{fun}{opt-tag @<option> @> @<tag>}
 258      \dhead{fun}{setf (opt-tag @<option>) @<tag>}
 259      \dhead{fun}{opt-negated-tag @<option> @> @<tag>}
 260      \dhead{fun}{setf (opt-negated-tag @<option>) @<tag>}
 261      \dhead{fun}{opt-arg-name @<option> @> @<string-or-null>}
 262      \dhead{fun}{setf (opt-arg-name @<option>) @<string-or-null>}
 263      \dhead{fun}{opt-optional-p @<option> @> @<generalized-boolean>}
 264      \dhead{fun}{setf (opt-optional-p @<option>) @<generalized-boolean>}
 265      \dhead{fun}{opt-documentation @<option> @> @<string-or-null>}
 266      \dhead{fun}{setf (opt-documentation @<option>) @<string-or-null>}}
 267 \end{describe*}
 268
 269 \begin{describe}{cls}{option-parser}
 270 \end{describe}
 271
 272 \begin{describe}{fun}{option-parser-p @<object> @> @<generalized-boolean>}
 273 \end{describe}
 274
 275 \begin{describe}{fun}
 276     {make-option-parser \&key \=:args :options :non-option :numericp \+ \\
 277                               :negated-numeric-p long-only-p \-
 278       \nlret @<option-parser>}
 279 \end{describe}
 280
 281 \begin{describe*}
 282     {\dhead{fun}{op-options @<option-parser> @> @<list>}
 283      \dhead{fun}{setf (op-options @<option-parser>) @<list>}
 284      \dhead{fun}{op-non-option @<option-parser> @> @<action>}
 285      \dhead{fun}{setf (op-non-option @<option-parser>) @<action>}
 286      \dhead{fun}{op-long-only-p @<option-parser> @> @<generalized-boolean>}
 287      \dhead{fun}{setf (op-long-only-p @<option-parser>) @<generalized-boolean>}
 288      \dhead{fun}{op-numeric-p @<option-parser> @> @<generalized-boolean>}
 289      \dhead{fun}{setf (op-numeric-p @<option-parser>) @<generalized-boolean>}
 290      \dhead{fun}{op-negated-numeric-p @<option-parser> @<generalized-boolean>}
 291      \dhead{fun}{setf (op-negated-numeric-p @<option-parser>) @<generalized-boolean>}
 292      \dhead{fun}{op-negated-p @<option-parser> @> @<generalized-boolean>}
 293      \dhead{fun}{setf (op-negated-p @<option-parser>) @<generalized-boolean>}}
 294 \end{describe*}
 295
 296 \begin{describe}{cls}
 297     {option-parse-error (error simple-condition)
 298       \&key :format-control :format-arguments}
 299 \end{describe}
 300
 301 \begin{describe}{fun}{option-parse-remainder @<option-parser>}
 302 \end{describe}
 303
 304 \begin{describe}{fun}{option-parse-return @<tag> \&optional @<argument>}
 305 \end{describe}
 306
 307 \begin{describe}{fun}{option-parse-next @<option-parser>}
 308 \end{describe}
 309
 310 \begin{describe}{mac}{option-parse-try @<body-form>^*}
 311 \end{describe}
 312
 313 \begin{describe}{mac}{with-unix-error-reporting () @<body-form>^*}
 314 \end{describe}
 315
 316 \begin{describe}{mac}
 317     {defopthandler @<name> (@<var> @[@<arg>@]) @<lambda-list> \\ \ind
 318       @<body-form>^*}
 319 \end{describe}
 320
 321 \begin{describe}{fun}
 322     {invoke-option-handler @<handler> @<locative> @<arg> @<arguments>}
 323 \end{describe}
 324
 325 \begin{describe}{opt}{set \&optional @<value>}
 326 \end{describe}
 327
 328 \begin{describe}{opt}{clear \&optional @<value>}
 329 \end{describe}
 330
 331 \begin{describe}{opt}{inc \&optional @<maximum> @<step>}
 332 \end{describe}
 333
 334 \begin{describe}{opt}{dec \&optional <minimum> <step>}
 335 \end{describe}
 336
 337 \begin{describe}{opt}{read}
 338 \end{describe}
 339
 340 \begin{describe}{opt}{int \&key :radix :min :max}
 341 \end{describe}
 342
 343 \begin{describe}{opt}{string}
 344 \end{describe}
 345
 346 \begin{describe}{opt}{keyword \&optional @<valid>}
 347 \end{describe}
 348
 349 \begin{describe}{opt}{list \&optional @<handler> \&rest @<handler-args>}
 350 \end{describe}
 351
 352 \begin{describe}{mac}{defoptmacro @<name> @<lambda-list> @<body-form>^*}
 353 \end{describe}
 354
 355 \begin{describe}{fun}{parse-option-form @<form>}
 356 \end{describe}
 357
 358 \begin{describe}{mac}
 359     {options @{ \=@<string> @! \+ \\
 360                   @<option-macro> @! (@<option-macro> @<macro-arg>^*) @! \\
 361                   (@[[ \=@<character> @! (:short-name @<character>) @! \+ \\
 362                          @<string>^* @! @<symbol> @! @<rational> @!
 363                          (:long-name @<string>) @! \\
 364                          (@<string> @<format-arg>^+) @!
 365                          (:doc @<string> @<format-arg>^*) @! \\
 366                          (:opt-arg @<arg-name>) @! \\
 367                          @<keyword> @! (:tag @<tag>) @!
 368                                        (:negated-tag @<tag>) @! \\
 369                          @{ (@<handler> @<var> @<handler-arg>^*) @}^* @]]) @}^*}
 370 \end{describe}
 371
 372 \begin{describe}{fun}
 373     {simple-usage @<option-list> \&optional @<mandatory-args> @> @<list>}
 374 \end{describe}
 375
 376 \begin{describe}{fun}{show-usage @<prog> @<usage> \&optional @<stream>}
 377 \end{describe}
 378
 379 \begin{describe}{fun}
 380     {show-help @<prog> @<usage> @<option-list> \&optional @<stream>}
 381 \end{describe}
 382
 383 \begin{describe}{fun}{sanity-check-option-list @<option-list>}
 384 \end{describe}
 385
 386 \begin{describe*}
 387     {\dhead{var}{*help*}
 388      \dhead{var}{*version*}
 389      \dhead{var}{*usage*}}
 390 \end{describe*}
 391
 392 \begin{describe}{fun}{do-usage \&optional @<stream>}
 393 \end{describe}
 394
 395 \begin{describe}{fun}{die-usage}
 396 \end{describe}
 397
 398 \begin{describe}{optmac}
 399     {help-options \&key :short-help :short-version :short-usage}
 400 \end{describe}
 401
 402 \begin{describe}{fun}
 403     {define-program \&key \=:program-name \+ \\
 404                             :help :version :usage :full-usage \\
 405                             :options}
 406 \end{describe}
 407
 408 \begin{describe}{mac}
 409     {do-options (@[[ :parser @<option-parser> @]]) \\ \ind
 410       @{ (@{ @<case> @! (@<case>^*)@} (@[@[@<opt-var>@] @<arg-var>@])
 411           @<form>^*) @}^*}
 412 \end{describe}
 413
 414 %%%--------------------------------------------------------------------------
 415 \section{Property sets} \label{sec:misc.pset}
 416
 417 %%%--------------------------------------------------------------------------
 418 \section{Miscellaneous translator features} \label{sec:misc.pset}
 419
 420 \begin{describe}{var}{*sod-version*}
 421 \end{describe}
 422
 423 \begin{describe}{var}{*debugout-pathname*}
 424 \end{describe}
 425
 426 \begin{describe}{fun}{test-module @<path> @<reason>}
 427 \end{describe}
 428
 429 \begin{describe}{fun}{exercise}
 430 \end{describe}
 431
 432 %%%----- That's all, folks --------------------------------------------------
 433
 434 %%% Local variables:
 435 %%% mode: LaTeX
 436 %%% TeX-master: "sod.tex"
 437 %%% TeX-PDF-mode: t
 438 %%% End: