[sod] / doc / misc.tex

%%% -*-latex-*-
%%%
%%% Miscellaneous functionality
%%%
%%% (c) 2015 Straylight/Edgeware
%%%

%%%----- Licensing notice ---------------------------------------------------
%%%
%%% This file is part of the Sensible Object Design, an object system for C.
%%%
%%% SOD is free software; you can redistribute it and/or modify
%%% it under the terms of the GNU General Public License as published by
%%% the Free Software Foundation; either version 2 of the License, or
%%% (at your option) any later version.
%%%
%%% SOD is distributed in the hope that it will be useful,
%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%%% GNU General Public License for more details.
%%%
%%% You should have received a copy of the GNU General Public License
%%% along with SOD; if not, write to the Free Software Foundation,
%%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

\chapter{Miscellaneous functionality} \label{ch:misc}

%%%--------------------------------------------------------------------------
\section{Utilities} \label{sec:misc.utilities}

These symbols are defined in the @|sod-utilities| package.

\begin{describe}{mac}
    {with-gensyms (@{ @<var> @! (@<var> @[@<name>@]) @}^*) \\ \ind
      @<declaration>^* \\
      @<form>^*}
\end{describe}

\begin{describe}{mac}
    {once-only (@[[ :environment @<env> @]]
                @{ @<var> @! (@<var> @[@<value-form>@]) @}^*) \\ \ind
      @<declaration>^* \\
      @<form>^*}
\end{describe}

\begin{describe}{mac}
    {parse-body @<body> \&key :docp :declp
      @> @<doc-string> @<declarations> @<body-forms>}
\end{describe}

\begin{describe}{cls}{loc}
\end{describe}

\begin{describe}{fun}{locp @<object> @> @<generalized-boolean>}
\end{describe}

\begin{describe}{mac}{locf @<place> @> @<locative>}
\end{describe}

\begin{describe*}
    {\dhead{fun}{ref @<locative> @> @<value>}
     \dhead{fun}{setf (ref @<locative>) @<value>}}
\end{describe*}

\begin{describe}{mac}
    {with-locatives
        @{ @<var> @! (@{ @<var> @!
                         (@<var> @[@<locative>@]) @}^*) @} \\ \ind
      @<declaration>^* \\
      @<form>^*}
\end{describe}

\begin{describe}{sym}{it}
\end{describe}

\begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@]}
\end{describe}

\begin{describe}{mac}{awhen @<condition> @<form>^*}
\end{describe}

\begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^*}
\end{describe}

\begin{describe*}
    {\dhead{mac}
      {acase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
     \dhead{mac}
      {aecase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
     \dhead{mac}{atypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}
     \dhead{mac}{aetypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}}
\end{describe*}

\begin{describe}{mac}{asetf @{ @<place> @<value> @}^*}
\end{describe}

\begin{describe}{gf}{instance-initargs @<instance>}
\end{describe}

\begin{describe*}
    {\dhead{fun}{copy-instance @<instance> \&rest @<initargs>}
     \dhead{gf}{copy-instance-using-class @<class> @<instance>
                                          \&rest @<initargs>}}
\end{describe*}

\begin{describe*}
    {\dhead{gf}{generic-function-methods @<generic-function> @> @<list>}
     \dhead{gf}{method-specializers @<method> @> @<list>}
     \dhead{cls}{eql-specializer}
     \dhead{gf}{eql-specializer-object @<specializer> @> @<value>}}
\end{describe*}

\begin{describe}{fun}{make-list-builder \&optional @<initial> @> @<builder>}
\end{describe}

\begin{describe}{fun}{lbuild-add @<builder> @<item> @> @<builder>}
\end{describe}

\begin{describe}{fun}{lbuild-add-list @<builder> @<list> @> @<builder>}
\end{describe}

\begin{describe}{fun}{lbuild-list @<builder> @> @<list>}
\end{describe}

\begin{describe}{fun}
    {mappend @<function> @<list> \&rest @<more-lists> @> @<result-list>}
\end{describe}

\begin{describe}{cls}{inconsistent-merge-error (error) \&key :candidates}
\end{describe}

\begin{describe}{gf}{merge-error-candidates @<error> @> @<list>}
\end{describe}

\begin{describe}{fun}
    {merge-lists @<lists> \&key :pick (:test \#'eql) @> @<list>}
\end{describe}

\begin{describe}{mac}
    {categorize (\=@<item-var> @<items>
                   @[[ :bind (@{ @<var> @! (@<var> @[@<value>@]) @}^*) @]])
                                                                 \\ \ind\ind
        (@{ (@<cat-var> @<cat-predicate>) @}^*) \- \\
      @<declaration>^* \\
      @<body-form>^* \-
     \nlret @<value>^*}
\end{describe}

\begin{describe}{fun}
    {frob-identifier @<string> \&key :swap-case :swap-hyphen
      @> @<frobbed-string>}
\end{describe}

\begin{describe}{fun}{whitespace-char-p @<character> @> @<generic-function>}
\end{describe}

\begin{describe}{fun}
    {update-position @<character> @<line> @<column>
      @> @<new-line> @<new-column>}
\end{describe}

\begin{describe}{fun}
    {backtrack-position @<character> @<line> @<column>
      @> @<old-line> @<old-column>}
\end{describe}

\begin{describe}{fun}
    {compose @<function> \&rest @<more-functions> @> @<function>}
\end{describe}

\begin{describe}{fun}{symbolicate \&rest @<symbols> @> @<symbol>}
\end{describe}

\begin{describe}{mac}
    {maybe-print-unreadable-object (@<object> @<stream>
                                    @[[ :type @<type> @!
                                        :identity @<identity> @]]) \\ \ind
      @<declaration>^* \\
      @<form>^*}
\end{describe}

\begin{describe}{mac}
    {dosequence (@<var> @<sequence>
                 @[[ :start @<start> @! :end @<end> @!
                     :indexvar @<var> @]]) \\ \ind
      @<declaration>^* \\
      @{ @<tag> @! @<statement> @}^*}
\end{describe}

\begin{describe}{mac}
    {define-access-wrapper @<from> @<to>
                           @[[ :read-only @<read-only-flag> @]]}
\end{describe}

\begin{describe}{mac}
    {default-slot (@<instance> @<slot> @[@<slot-names>@]) \\ \ind
      @<form>^*}
\end{describe}

\begin{describe}{mac}
    {define-on-demand-slot @<class> @<slot> (@<instance>) \\ \ind
      @[[ @<declaration>^* @! @<doc-string> @]] \\
      @<form>^*}
\end{describe}

%%%--------------------------------------------------------------------------
\section{Condition utilities} \label{sec:misc.condition}

These symbols are defined in the @|sod-parser| package.

\begin{describe}{cls}{enclosing-condition (condition) \&key :condition}
\end{describe}

\begin{describe}{gf}
    {enclosed-condition @<enclosing-condition> @> @<condition>}
\end{describe}

\begin{describe}{fun}{cerror* @<datum> \&rest @<arguments>}
\end{describe}

%%%--------------------------------------------------------------------------
\section{Option parser} \label{sec:misc.optparse}

These symbols are defined in the @!optparse| package.

\begin{describe}{fun}{exit \&optional (@<code> 0) \&key :abrupt}
\end{describe}

\begin{describe}{var}{*program-name*}
\end{describe}

\begin{describe}{var}{*command-line*}
\end{describe}

\begin{describe}{fun}{set-command-line-arguments}
\end{describe}

\begin{describe}{fun}{moan @<format-string> \&rest @<format-args>}
\end{describe}

\begin{describe}{fun}{die @<format-string> \&rest @<format-args>}
\end{describe}

\begin{describe}{var}{*options*}
\end{describe}

\begin{describe}{cls}{option}
\end{describe}

\begin{describe}{fun}{optionp @<object> @> @<generalized-boolean>}
\end{describe}

\begin{describe}{fun}
    {make-option \=@<long-name> @<short-name> \+ \\
                   \&optional @<arg-name> \\
                   \&key :tag :negated-tag :arg-optional-p :documentation \-
      \nlret @<option>}
\end{describe}

\begin{describe*}
    {\dhead{fun}{opt-short-name @<option> @> @<character-or-null>}
     \dhead{fun}{setf (opt-short-name @<option>) @<character-or-null>}
     \dhead{fun}{opt-long-name @<option> @> @<string-or-null>}
     \dhead{fun}{setf (opt-long-name @<option>) @<string-or-null>}
     \dhead{fun}{opt-tag @<option> @> @<tag>}
     \dhead{fun}{setf (opt-tag @<option>) @<tag>}
     \dhead{fun}{opt-negated-tag @<option> @> @<tag>}
     \dhead{fun}{setf (opt-negated-tag @<option>) @<tag>}
     \dhead{fun}{opt-arg-name @<option> @> @<string-or-null>}
     \dhead{fun}{setf (opt-arg-name @<option>) @<string-or-null>}
     \dhead{fun}{opt-optional-p @<option> @> @<generalized-boolean>}
     \dhead{fun}{setf (opt-optional-p @<option>) @<generalized-boolean>}
     \dhead{fun}{opt-documentation @<option> @> @<string-or-null>}
     \dhead{fun}{setf (opt-documentation @<option>) @<string-or-null>}}
\end{describe*}

\begin{describe}{cls}{option-parser}
\end{describe}

\begin{describe}{fun}{option-parser-p @<object> @> @<generalized-boolean>}
\end{describe}

\begin{describe}{fun}
    {make-option-parser \&key \=:args :options :non-option :numericp \+ \\
                              :negated-numeric-p long-only-p \-
      \nlret @<option-parser>}
\end{describe}

\begin{describe*}
    {\dhead{fun}{op-options @<option-parser> @> @<list>}
     \dhead{fun}{setf (op-options @<option-parser>) @<list>}
     \dhead{fun}{op-non-option @<option-parser> @> @<action>}
     \dhead{fun}{setf (op-non-option @<option-parser>) @<action>}
     \dhead{fun}{op-long-only-p @<option-parser> @> @<generalized-boolean>}
     \dhead{fun}{setf (op-long-only-p @<option-parser>) @<generalized-boolean>}
     \dhead{fun}{op-numeric-p @<option-parser> @> @<generalized-boolean>}
     \dhead{fun}{setf (op-numeric-p @<option-parser>) @<generalized-boolean>}
     \dhead{fun}{op-negated-numeric-p @<option-parser> @<generalized-boolean>}
     \dhead{fun}{setf (op-negated-numeric-p @<option-parser>) @<generalized-boolean>}
     \dhead{fun}{op-negated-p @<option-parser> @> @<generalized-boolean>}
     \dhead{fun}{setf (op-negated-p @<option-parser>) @<generalized-boolean>}}
\end{describe*}

\begin{describe}{cls}
    {option-parse-error (error simple-condition)
      \&key :format-control :format-arguments}
\end{describe}

\begin{describe}{fun}{option-parse-remainder @<option-parser>}
\end{describe}

\begin{describe}{fun}{option-parse-return @<tag> \&optional @<argument>}
\end{describe}

\begin{describe}{fun}{option-parse-next @<option-parser>}
\end{describe}

\begin{describe}{mac}{option-parse-try @<form>^*}
\end{describe}

\begin{describe}{mac}{with-unix-error-reporting () @<form>^*}
\end{describe}

\begin{describe}{mac}
    {defopthandler @<name> (@<var> @[@<arg>@]) @<lambda-list> \\ \ind
      @[[ @<declaration>^* @! @<doc-string> @]] \\
      @<form>^*}
\end{describe}

\begin{describe}{fun}
    {invoke-option-handler @<handler> @<locative> @<arg> @<arguments>}
\end{describe}

\begin{describe}{opt}{set \&optional @<value>}
\end{describe}

\begin{describe}{opt}{clear \&optional @<value>}
\end{describe}

\begin{describe}{opt}{inc \&optional @<maximum> @<step>}
\end{describe}

\begin{describe}{opt}{dec \&optional <minimum> <step>}
\end{describe}

\begin{describe}{opt}{read}
\end{describe}

\begin{describe}{opt}{int \&key :radix :min :max}
\end{describe}

\begin{describe}{opt}{string}
\end{describe}

\begin{describe}{opt}{keyword \&optional @<valid>}
\end{describe}

\begin{describe}{opt}{list \&optional @<handler> \&rest @<handler-args>}
\end{describe}

\begin{describe}{mac}
    {defoptmacro @<name> @<lambda-list> \\ \ind
      @[[ @<declaration>^* @! @<doc-string> @]] \\
      @<form>^*}
\end{describe}

\begin{describe}{fun}{parse-option-form @<form>}
\end{describe}

\begin{describe}{mac}
    {options @{ \=@<string> @! \+ \\
                  @<option-macro> @! (@<option-macro> @<macro-arg>^*) @! \\
                  (@[[ \=@<character> @! (:short-name @<character>) @! \+ \\
                         @<string>^* @! @<symbol> @! @<rational> @!
                         (:long-name @<string>) @! \\
                         (@<string> @<format-arg>^+) @!
                         (:doc @<string> @<format-arg>^*) @! \\
                         (:arg @<arg-name>) @! (:opt-arg @<arg-name>) @! \\
                         @<keyword> @! (:tag @<tag>) @!
                                       (:negated-tag @<tag>) @! \\
                         @{ (@<handler> @<var> @<handler-arg>^*) @}^*
                   @]]) @}^*}
\end{describe}

\begin{describe}{fun}
    {simple-usage @<option-list> \&optional @<mandatory-args> @> @<list>}
\end{describe}

\begin{describe}{fun}{show-usage @<prog> @<usage> \&optional @<stream>}
\end{describe}

\begin{describe}{fun}
    {show-help @<prog> @<usage> @<option-list> \&optional @<stream>}
\end{describe}

\begin{describe}{fun}{sanity-check-option-list @<option-list>}
\end{describe}

\begin{describe*}
    {\dhead{var}{*help*}
     \dhead{var}{*version*}
     \dhead{var}{*usage*}}
\end{describe*}

\begin{describe}{fun}{do-usage \&optional @<stream>}
\end{describe}

\begin{describe}{fun}{die-usage}
\end{describe}

\begin{describe}{optmac}
    {help-options \&key :short-help :short-version :short-usage}
\end{describe}

\begin{describe}{fun}
    {define-program \&key \=:program-name \+ \\
                            :help :version :usage :full-usage \\
                            :options}
\end{describe}

\begin{describe}{mac}
    {do-options (@[[ :parser @<option-parser> @]]) \\ \ind
      @{ (@{ @<case> @! (@<case>^*)@} (@[@[@<opt-var>@] @<arg-var>@])
          @<form>^*) @}^*}
\end{describe}

%%%--------------------------------------------------------------------------
\section{Property sets} \label{sec:misc.pset}

\begin{describe}{fun}{property-key @<name> @> @<keyword>}
\end{describe}

\begin{describe}{gf}{decode-property @<raw-value> @> @<type> @<value>}
\end{describe}

\begin{describe}{cls}{property}
\end{describe}

\begin{describe}{fun}{propertyp @<object> @> @<generalized-boolean>}
\end{describe}

\begin{describe}{fun}
    {make-property @<name> @<raw-value> \&key :type :location :seenp}
\end{describe}

\begin{describe*}
    {\dhead{fun}{p-name @<property> @> @<name>}
     \dhead{fun}{p-value @<property> @> @<value>}
     \dhead{fun}{p-type @<property> @> @<type>}
     \dhead{fun}{p-key @<property> @> @<symbol>}
     \dhead{fun}{p-seenp @<property> @> @<boolean>}
     \dhead{fun}{setf (p-seenp @<property>) @<boolean>}}
\end{describe*}

\begin{describe}{gf}{decode-property @<raw-value> @> @<type> @<value>}
\end{describe}

\begin{describe}{gf}
    {coerce-property-value @<value> @<type> @<wanted> @> @<coerced-value>}
\end{describe}

\begin{describe}{cls}{pset}
\end{describe}

\begin{describe}{fun}{psetp @<object> @> @<generalized-boolean>}
\end{describe}

\begin{describe}{fun}{make-pset @> @<pset>}
\end{describe}

\begin{describe}{fun}{pset-get @<pset> @<key> @> @<property-or-nil>}
\end{describe}

\begin{describe}{fun}{pset-store @<pset> @<property> @> @<property>}
\end{describe}

\begin{describe}{fun}{pset-map @<func> @<pset>}
\end{describe}

\begin{describe}{mac}
    {with-pset-iterator (@<iter> @<pset>) @<declaration>^* @<form>^*}
\end{describe}

\begin{describe}{fun}
    {store-property @<pset> @<name> @<value> \&key :type :location
      @> @<property>}
\end{describe}

\begin{describe}{fun}
    {get-property @<pset> @<name> @<type> \&optional @<default>
      @> @<value> @<floc-or-nil>}
\end{describe}

\begin{describe}{fun}
    {add-property @<pset> @<name> @<value> \&key :type :location
      @> @<property>}
\end{describe}

\begin{describe}{fun}{make-property-set \&rest @<plist> @> @<pset>}
\end{describe}

\begin{describe}{gf}{property-set @<thing> @> @<pset>}
\end{describe}

\begin{describe}{fun}{check-unused-properties @<pset>}
\end{describe}

\begin{describe}{mac}
    {default-slot-from-property
        (@<instance> @<slot> @[@<slot-names>@]) \\ \ind\ind
        (@<pset> @<property> @<type> @[@<prop-var> @<convert-form>^*@]) \- \\
      @<declaration>^* \\
      @<default-form>^*}
\end{describe}

\begin{describe}{fun}
    {parse-property-set @<scanner>
      @> @<result> @<success-flag> @<consumed-flag>}
\end{describe}

%%%--------------------------------------------------------------------------
\section{Miscellaneous translator features} \label{sec:misc.pset}

\begin{describe}{var}{*sod-version*}
\end{describe}

\begin{describe}{var}{*debugout-pathname*}
\end{describe}

\begin{describe}{fun}{test-module @<path> @<reason>}
\end{describe}

\begin{describe}{fun}{exercise}
\end{describe}

\begin{describe}{fun}{sod-frontend:main}
\end{describe}

%%%----- That's all, folks --------------------------------------------------

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