Skip to content

Commit c2b14a6

Browse files
eernstgeernstg
committed
Review response
1 parent 1f00fec commit c2b14a6

File tree

2 files changed

+356
-229
lines changed

2 files changed

+356
-229
lines changed

‎specification/dart.sty

Lines changed: 133 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@
136136
\newcommand{\Case}[1]{\textbf{Case }$\langle\hspace{0.1em}${#1}$\hspace{0.1em}\rangle$\textbf{.}}
137137
\newcommand{\EndCase}{\mbox{}\hfill$\scriptscriptstyle\Box$\xspace}
138138

139+
% Used for source code examples.
139140
\newenvironment{dartCode}[1][!ht]{%
140141
\def\@programcr{\@addfield\strut}%
141142
\let\\=\@programcr%
@@ -144,6 +145,7 @@
144145
\vspace{1em}%
145146
}{\normalcolor\vspace{1em}}
146147

148+
% Used for normative code snippets (mainly desugaring).
147149
\newenvironment{normativeDartCode}[1][!ht]{%
148150
\def\@programcr{\@addfield\strut}%
149151
\let\\=\@programcr%
@@ -152,6 +154,9 @@
152154
\vspace{1em}%
153155
}{\normalcolor\vspace{1em}}
154156

157+
% Used for meta-level code, such as the code transformations used
158+
% to specify the semantics of "null shorting" in expressions like
159+
% `a?.b.c`.
155160
\newenvironment{metaLevelCode}[1][!ht]{%
156161
\def\@programcr{\@addfield\strut}%
157162
\let\\=\@programcr%
@@ -206,20 +211,37 @@
206211
\newcommand{\PairList}[4]{\ensuremath{%
207212
{#1}_{#3}\ {#2}_{#3},\,\ldots,\ {#1}_{#4}\ {#2}_{#4}}}
208213

209-
% Used to specify named arguments.
210-
% Parameters: Parameter name, argument name, index at start, index at end.
214+
% A sequence of labeled arguments with the same label and expression,
215+
% only differing by subscript.
216+
% Parameters: Argument label, argument expression, start index,
217+
% end index.
218+
%
219+
% For example, \NamedArgumentList{n}{e}{1}{k} yields approximately
220+
% "n1: e1, n2: e2, ... nk: ek".
211221
\newcommand{\NamedArgumentList}[4]{\PairList{#1}{\!\!:\,\,{#2}}{#3}{#4}}
212222

213-
% Used to specify an argument list including positional and named arguments.
214-
% Parameters: Argument name, number of positional arguments, named parameter
215-
% name, number of named arguments.
223+
% A sequence of unlabeled and labeled arguments with the same expression and
224+
% (for all labeled arguments) the same label, only differing by subscript.
225+
% Parameters: Argument name, number of positional arguments, labeled parameter
226+
% label, number of labeled arguments.
227+
%
228+
% For example, \ArgumentList{a}{n}{x}{k} yields approximately
229+
% "a1, .. an, xn+1: an+1, .. xn+k: an+k".
216230
\newcommand{\ArgumentList}[4]{%
217231
\List{#1}{1}{#2},\ \NamedArgumentList{#3}{#1}{{#2}+1}{{#2}+{#4}}}
218232

219-
% Used to specify a standard argument list.
233+
% Used to specify a standard argument list, that is, an argument list
234+
% which uses the symbols that we prefer to use for that purpose
235+
% whenever possible.
236+
%
237+
% Approximately "a1 .. an, xn+1: an+1 .. xn+k: an+k".
220238
\newcommand{\ArgumentListStd}{\ArgumentList{a}{n}{x}{k}}
221239

222-
% Used to specify a standard type argument list.
240+
% Used to specify a standard type argument list, that is, a type
241+
% argument list which uses the symbols we prefer to use for that
242+
% purpose whenever possible.
243+
%
244+
% Approximately "A1 .. Ar".
223245
\newcommand{\TypeArgumentListStd}{\List{A}{1}{r}}
224246

225247
% Used to specify a list of tuples of the form $(K_j, V_j)$ which are
@@ -256,7 +278,11 @@
256278
\newcommand{\TypeParametersNoBounds}[2]{\ensuremath{%
257279
{#1}_1\,\EXTENDS\,\ldots,\ \ldots,\ {#1}_{#2}\,\EXTENDS\,\ldots}}
258280

259-
% For consistency, we may as well use this whenever possible.
281+
% Used to specify a standard type parameter list, that is, a type
282+
% parameter declaration list which uses the symbols we prefer to use
283+
% for that purpose whenever possible.
284+
%
285+
% Approximately "X1 extends B1, .. Xs extends Bs".
260286
\newcommand{\TypeParametersStd}{\TypeParameters{X}{B}{s}}
261287

262288
% Used to specify comma separated lists of pairs of symbols
@@ -288,83 +314,140 @@
288314

289315
% Used to specify function type parameter lists with positional optionals.
290316
% Arguments: Parameter type, number of required parameters,
291-
% number of optional parameters.
292-
\newcommand{\FunctionTypePositionalArguments}[3]{%
317+
% number of optional parameters.
318+
%
319+
% For example, \FunctionTypePositionalParameters{T}{n}{k} yields
320+
% approximately "T1, .. Tn, [Tn+1, .. Tn+k]".
321+
\newcommand{\FunctionTypePositionalParameters}[3]{%
293322
\List{#1}{1}{#2},\ [\List{#1}{{#2}+1}{{#2}+{#3}}]}
294323

295-
\newcommand{\FunctionTypePositionalArgumentsStd}{%
296-
\FunctionTypePositionalArguments{T}{n}{k}}
324+
% Used to specify a standard positional function type, that is, a function
325+
% type with positional optional parameters which uses the symbols we prefer
326+
% to use for that purpose whenever possible.
327+
%
328+
% Approximately "T1, .. Tn, [Tn+1, .. Tn+k]".
329+
\newcommand{\FunctionTypePositionalParametersStd}{%
330+
\FunctionTypePositionalParameters{T}{n}{k}}
331+
332+
% Used to specify function type parameter lists with named optionals.
333+
% Arguments: Parameter type, number of required parameters,
334+
% name of optional parameters, number of optional parameters.
335+
%
336+
% For example \FunctionTypeNamedParameters{T}{n}{x}{k}{r} yields approximately
337+
% "T1, .. Tn, {rn+1 Tn+1 xn+1, .. rn+k Tn+k xn+k}".
338+
\newcommand{\FunctionTypeNamedParameters}[5]{%
339+
\List{#1}{1}{#2},\ \{\TripleList{#5}{#1}{#3}{{#2}+1}{{#2}+{#4}}\}}
340+
341+
% Variant of \FunctionTypeNamedParameters that uses the standard symbols,
342+
% that is, a list of function type parameter declarations with named
343+
% parameters which uses the symbols that we prefer to use for that purpose
344+
% whenever possible.
345+
%
346+
% Approximately "T1, .. Tn, {rn+1 Tn+1 xn+1, .. rn+k Tn+k xn+k}".
347+
\newcommand{\FunctionTypeNamedParametersStd}{%
348+
\FunctionTypeNamedParameters{T}{n}{x}{k}{r}}
297349

298350
% Used to specify function types with positional optionals:
299351
% Arguments: Return type, spacer, type parameter name, bound name,
300352
% number of type parameters, parameter type, number of required parameters,
301353
% number of optional parameters.
354+
%
355+
% For example, \FunctionTypePositional{R}{ }{X}{B}{s}{T}{n}{k} yields
356+
% approximately
357+
% "R Function<X1 extends B1, .. Xs extends Bs>(T1, .. Tn, [Tn+1, .. Tn+k])".
302358
\newcommand{\FunctionTypePositional}[8]{%
303359
\FunctionType{#1}{#2}{#3}{#4}{#5}{%
304-
\FunctionTypePositionalArguments{#6}{#7}{#8}}}
360+
\FunctionTypePositionalParameters{#6}{#7}{#8}}}
305361

306362
% Same as \FunctionTypePositional except suitable for inline usage,
307363
% hence omitting the spacer argument.
308364
\newcommand{\RawFunctionTypePositional}[7]{%
309365
\RawFunctionType{#1}{#2}{#3}{#4}{%
310-
\FunctionTypePositionalArguments{#5}{#6}{#7}}}
366+
\FunctionTypePositionalParameters{#5}{#6}{#7}}}
367+
368+
% A variant of \FunctionTypePositional that uses the standard symbols,
369+
% that is, a function type with positional optional parameters which
370+
% uses the symbols that we prefer to use for that purpose whenever
371+
% possible.
372+
%
373+
% For example, \FunctionTypePositionalStd{R} yields approximately
374+
% "R Function<X1 extends B1, .. Xs extends Bs>(T1, T2, .. Tn, [Tn+1 .. Tn+k])".
375+
\newcommand{\FunctionTypePositionalStd}[1]{%
376+
\FunctionTypePositional{#1}{ }{X}{B}{s}{T}{n}{k}}
311377

312-
% Used to specify function type parameter lists with named optionals.
313-
% Arguments: Parameter type, number of required parameters,
314-
% name of optional parameters, number of optional parameters,
315-
% name of `required` symbol.
316-
\newcommand{\FunctionTypeNamedArguments}[5]{%
317-
\List{#1}{1}{#2},\ \{\TripleList{#5}{#1}{#3}{{#2}+1}{{#2}+{#4}}\}}
318-
319-
\newcommand{\FunctionTypeNamedArgumentsStd}{%
320-
\FunctionTypeNamedArguments{T}{n}{x}{k}{r}}
378+
% Same as \FunctionTypePositionalStd except suitable for inline usage,
379+
% hence omitting the spacer argument.
380+
\newcommand{\RawFunctionTypePositionalStd}[1]{%
381+
\RawFunctionTypePositional{#1}{X}{B}{s}{T}{n}{k}}
382+
383+
% Same as \FunctionTypePositionalStd except that it includes a newline, hence
384+
% suitable for function types that are too long to fit in one line.
385+
\newcommand{\FunctionTypePositionalStdCr}[1]{%
386+
\FunctionTypePositional{#1}{\\}{X}{B}{s}{T}{n}{k}}
321387

322388
% Used to specify function types with named parameters:
323389
% Arguments: Return type, spacer, type parameter name, bound name,
324390
% number of type parameters, parameter type, number of required parameters,
325-
% name of optional parameters, number of optional parameters,
326-
% name of `required` symbol.
391+
% name of optional parameters, number of optional parameters.
392+
% The name of the `required` symbol is always `r` (because we can't have
393+
% 10 arguments in a LaTeX command, and `r` is always OK in practice).
394+
%
395+
% For example, \FunctionTypeNamed{R}{ }{X}{B}{s}{T}{n}{x}{k} yields
396+
% approximately "R Function<X1 extends B1, .. Xs extends Bs>(
397+
% T1, T2, .. Tn, {rn+1 Tn+1 xn+1, .. rn+k Tn+k xn+k])".
327398
\newcommand{\FunctionTypeNamed}[9]{%
328399
\FunctionType{#1}{#2}{#3}{#4}{#5}{\\
329-
\mbox{}\qquad\FunctionTypeNamedArguments{#6}{#7}{#8}{#9}{#10}}}
400+
\mbox{}\qquad\FunctionTypeNamedParameters{#6}{#7}{#8}{#9}{r}}}
330401

331-
% Same as \FunctionType except suitable for inline usage, hence omitting
402+
% Same as \FunctionTypeNamed except suitable for inline usage, hence omitting
332403
% the spacer argument.
333-
\newcommand{\RawFunctionTypeNamed}[9]{%
404+
\newcommand{\RawFunctionTypeNamed}[8]{%
334405
\RawFunctionType{#1}{#2}{#3}{#4}{%
335-
\FunctionTypeNamedArguments{#5}{#6}{#7}{#8}{#9}}}
406+
\FunctionTypeNamedParameters{#5}{#6}{#7}{#8}{r}}}
407+
408+
% A variant of \FunctionTypeNamed that uses the standard symbols,
409+
% that is, a function type with positional optional parameters which
410+
% uses the symbols that we prefer to use for that purpose whenever
411+
% possible.
412+
%
413+
% For example, \FunctionTypeNamedStd{R} yields approximately
414+
% "R Function<X1 extends B1, .. Xs extends Bs>(
415+
% T1, T2, .. Tn, {rn+1 Tn+1 xn+1, .. rn+k Tn+k xn+k})".
416+
\newcommand{\FunctionTypeNamedStd}[1]{%
417+
\FunctionTypeNamed{#1}{ }{X}{B}{s}{T}{n}{x}{k}}
418+
419+
% Same as \FunctionTypeNamedStd except suitable for inline usage, hence
420+
% omitting the spacer argument.
421+
\newcommand{\RawFunctionTypeNamedStd}[1]{%
422+
\RawFunctionTypeNamed{#1}{X}{B}{s}{T}{n}{x}{k}{r}}
423+
424+
% Same as \FunctionTypeNamedStd except that it includes a newline, hence
425+
% suitable for function types that are too long to fit in one line.
426+
\newcommand{\FunctionTypeNamedStdCr}[1]{%
427+
\FunctionTypeNamed{#1}{\\}{X}{B}{s}{T}{n}{x}{k}}
336428

337429
% Used to specify function types with no optional parameters:
338430
% Arguments: Return type, spacer, type parameter name, bound name,
339431
% number of type parameters, parameter type,
340432
% number of parameters (all required).
433+
%
434+
% For example, \FunctionTypeAllRequired{R}{ }{X}{B}{s}{T}{n} yields
435+
% approximately "R Function<X1 extends B1, .. Xs extends Bs>(T1, T2, .. Tn)".
341436
\newcommand{\FunctionTypeAllRequired}[7]{%
342437
\FunctionType{#1}{#2}{#3}{#4}{#5}{\List{#6}{1}{#7}}}
343438

344-
\newcommand{\FunctionTypePositionalStd}[1]{%
345-
\FunctionTypePositional{#1}{ }{X}{B}{s}{T}{n}{k}}
346-
347-
\newcommand{\RawFunctionTypePositionalStd}[1]{%
348-
\RawFunctionTypePositional{#1}{X}{B}{s}{T}{n}{k}}
349-
350-
\newcommand{\FunctionTypeNamedStd}[1]{%
351-
\FunctionTypeNamed{#1}{ }{X}{B}{s}{T}{n}{x}{k}{r}}
352-
353-
\newcommand{\RawFunctionTypeNamedStd}[1]{%
354-
\RawFunctionTypeNamed{#1}{X}{B}{s}{T}{n}{x}{k}{r}}
355-
439+
% A variant of \FunctionTypeAllRequired that uses the standard symbols,
440+
% that is, a function type with positional optional parameters which
441+
% uses the symbols that we prefer to use for that purpose whenever
442+
% possible.
443+
%
444+
% For example, \FunctionTypeAllRequiredStd{R} yields approximately
445+
% "R Function<X1 extends B1, .. Xs extends Bs>(T1, T2, .. Tn)".
356446
\newcommand{\FunctionTypeAllRequiredStd}[1]{%
357447
\FunctionTypeAllRequired{#1}{ }{X}{B}{s}{T}{n}}
358448

359-
\newcommand{\FunctionTypePositionalStdCr}[1]{%
360-
\FunctionTypePositional{#1}{\\}{X}{B}{s}{T}{n}{k}}
361-
362-
\newcommand{\FunctionTypeNamedStdCr}[1]{%
363-
\FunctionTypeNamed{#1}{\\}{X}{B}{s}{T}{n}{x}{k}{r}}
364-
365-
\newcommand{\FunctionTypeNamedStdArgCr}[1]{%
366-
\FunctionTypeNamedArgCr{#1}{ }{X}{B}{s}{T}{n}{x}{k}{r}}
367-
449+
% Same as \FunctionTypeAllRequiredStd except that it includes a newline, hence
450+
% suitable for function types that are too long to fit in one line.
368451
\newcommand{\FunctionTypeAllRequiredStdCr}[1]{%
369452
\FunctionTypeAllRequired{#1}{\\}{X}{B}{s}{T}{n}}
370453

0 commit comments

Comments
 (0)