Skip to content

Commit ac48220

Browse files
martin-henzmartin-henz
authoredJul 23, 2020
Better docs (#685)
* fixes #567 * fixes #568 and restructures the documents
·
v1.0.23v1.0.21
1 parent af5dc72 commit ac48220

28 files changed

+405
-146
lines changed
 

‎docs/specs/Makefile

+1-3
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,11 @@ SPECS = $(SPECSNUMS:%=source_%)
66

77
PDFSPECS = $(SPECS:%=%.pdf)
88

9-
HELPERS = header bnf comments intro names numbers return strings typing objects arrays interpreter lists array_support loops boolean_operators pair_mutators 1_stepper_rules
10-
119
HELPERSTEX = $(HELPERS:%=source_%.tex)
1210

1311
all: $(PDFSPECS)
1412

15-
%.pdf: %.tex $(HELPERSTEX)
13+
%.pdf: %.tex
1614
$(PDFLATEX) $*
1715

1816
clean:

‎docs/specs/source_1.tex

+10-4
Original file line numberDiff line numberDiff line change
@@ -13,21 +13,27 @@
1313

1414
\newpage
1515

16+
\input source_return
17+
1618
\input source_import
1719

1820
\input source_boolean_operators
1921

20-
\input source_return
21-
22-
\input source_names
22+
\input source_names_lang
2323

2424
\input source_numbers
2525

2626
\input source_strings
2727

28+
\input source_comments
29+
2830
\input source_typing
2931

30-
\input source_comments
32+
\section{Standard Libraries}
33+
34+
The following library is always available in this language.
35+
36+
\input source_misc
3137

3238
\input source_js_differences
3339

‎docs/specs/source_1_bnf_without_import.tex

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
\begin{alignat*}{9}
2+
&& \textit{program} &&\quad ::= &\quad && \textit{statement} \ \ldots
3+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/3.1.1.html\#p6}{program}} \\[1mm]
4+
&& \textit{statement} &&\quad ::= &\quad && \textbf{\texttt{const}}\ \textit{name} \
5+
\textbf{\texttt{=}}\ \textit{expression} \ \textbf{\texttt{;}}
6+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.2.html\#p2}{constant declaration}} \\
7+
&& && | &\quad && \textbf{\texttt{function}}\ \textit{name} \
8+
\textbf{\texttt{(}}\ \textit{parameters} \ \textbf{\texttt{)}}\ \textit{block} \quad
9+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p4}{function declaration}}\\
10+
&& && | &\quad && \textbf{\texttt{return}}\ \textit{expression} \ \textbf{\texttt{;}}
11+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p4}{return statement}}\\
12+
&& && | &\quad && \textit{if-statement} \quad
13+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.3.2.html\#p13}{conditional statement}}\\
14+
&& && | &\quad && \textit{block}
15+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.8.html\#p14}{block statement}}\\
16+
&& && | &\quad && \textit{expression} \ \textbf{\texttt{;}}
17+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p3}{expression statement}} \\[1mm]
18+
&& \textit{parameters} && ::= &\quad && \epsilon\ | \ \textit{name} \
19+
(\ \textbf{\texttt{,}} \ \textit{name}\ )\ \ldots
20+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p4}{function parameters}} \\[1mm]
21+
&& \textit{if-statement} && ::= &\quad && \textbf{\texttt{if}}\
22+
\textbf{\texttt{(}}\ \textit{expression} \ \textbf{\texttt{)}}\
23+
\textit{block} \\
24+
&& && & && \textbf{\texttt{else}}\
25+
(\ \textit{block}
26+
\ | \
27+
\textit{\href{https://source-academy.github.io/sicp/chapters/1.3.3.html\#footnote-1}{if-statement}} \ )
28+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.3.2.html\#p12}{conditional statement}} \\[1mm]
29+
&& \textit{block} && ::= & && \textbf{\texttt{\{}}\ \textit{statement}\ \ldots \ \textbf{\texttt{\}}} \quad
30+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.8.html\#p14}{block statement}}\\[1mm]
31+
&& \textit{expression} && ::= &\quad && \textit{number} && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p3}{primitive number expression}}\\
32+
&& && | &\quad && \textbf{\texttt{true}}\ |\ \textbf{\texttt{false}}
33+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p1}{primitive boolean expression}}\\
34+
&& && | &\quad && \textit{string} && \textrm{\href{https://source-academy.github.io/sicp/chapters/2.3.1.html}{primitive string expression}}\\
35+
&& && | &\quad && \textit{name} && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.2.html}{name expression}}\\
36+
&& && | &\quad && \textit{expression} \ \textit{binary-operator} \
37+
\textit{expression} \qquad
38+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p5}{binary operator combination}}\\
39+
&& && | &\quad && \textit{unary-operator} \
40+
\textit{expression}
41+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{unary operator combination}}\\
42+
&& && | &\quad && \textit{expression} \
43+
\textbf{\texttt{(}}\ \textit{expressions}\
44+
\textbf{\texttt{)}}
45+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p5}{function application}}\\
46+
&& && | &\quad && (\ \textit{name}\ | \
47+
\textbf{\texttt{(}}\ \textit{parameters}\ \textbf{\texttt{)}}\
48+
)\
49+
\texttt{\textbf{=>}}\ \textit{expression}
50+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.3.2.html}{lambda expression (expr. body)}}\\
51+
&& && | &\quad && (\ \textit{name}\ | \
52+
\textbf{\texttt{(}}\ \textit{parameters}\ \textbf{\texttt{)}}\
53+
)\
54+
\texttt{\textbf{=>}}\ \textit{block}
55+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/2.2.4.html\#footnote-3}{lambda expression (block body)}}\\
56+
&& && | &\quad && \textit{expression} \ \textbf{\texttt{?}}\
57+
\textit{expression}
58+
\ \textbf{\texttt{:}}\
59+
\textit{expression}\
60+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p1}{conditional expression}}\\
61+
&& && | &\quad && \textbf{\texttt{(}}\ \textit{expression} \
62+
\textbf{\texttt{)}} && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p6}{parenthesised expression}}\\[1mm]
63+
&& \textit{binary-operator} \
64+
&& ::= &\quad && \textbf{\texttt{+}}\ |\ \textbf{\texttt{-}}\ |\ \textbf{\texttt{*}}\ |\ \textbf{\texttt{/}}\ |\ \textbf{\texttt{\%}}\ |\
65+
\textbf{\texttt{===}}\ |\ \textbf{\texttt{!==}}\ \\
66+
&& && | &\quad && \texttt{\textbf{>}}\ |\ \texttt{\textbf{<}}\ |\ \texttt{\textbf{>=}}\ |\ \texttt{\textbf{<=}}\
67+
|\ \textbf{\texttt{\&\&}}\ |\ \texttt{\textbf{||}}
68+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p4}{binary operator}}\\[1mm]
69+
&& \textit{unary-operator}
70+
&& ::= &\quad && \textbf{\texttt{!}}\ |\ \textbf{\texttt{-}}
71+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{unary operator}}\\[1mm]
72+
&& \textit{expressions} && ::= &\quad && \epsilon\ | \ \textit{expression}\ (
73+
\ \textbf{\texttt{,}} \
74+
\textit{expression} \
75+
)\ \ldots
76+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p5}{argument expressions}}
77+
\end{alignat*}

‎docs/specs/source_1_lazy.tex

+13-5
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
Source \S 1 Lazy is a lazy-evaluation variant of Source \S 1.
1414

15-
\section*{Changes}
15+
\section{Changes}
1616

1717
Source \S 1 Lazy modifies Source \S 1 by using
1818
lazy evaluation. In
@@ -38,19 +38,27 @@ \section*{Changes}
3838

3939
\newpage
4040

41-
\input source_boolean_operators
42-
4341
\input source_return
4442

45-
\input source_names
43+
\input source_import
44+
45+
\input source_boolean_operators
46+
47+
\input source_names_lang
4648

4749
\input source_numbers
4850

4951
\input source_strings
5052

53+
\input source_comments
54+
5155
\input source_typing
5256

53-
\input source_comments
57+
\section{Standard Libraries}
58+
59+
The following library is always available in this language.
60+
61+
\input source_misc
5462

5563
\input source_js_differences
5664

‎docs/specs/source_1_wasm.tex

+11-5
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828

2929
This document specifies the dialect of Source \S 1 used in Sourceror, an experimental compiler from Source \S 1 to WebAssembly. This dialect is a subset of Source \S 1.
3030

31-
\section*{Changes compared to Vanilla Source \S 1}
31+
\section{Changes compared to Vanilla Source \S 1}
3232

3333
\subsection*{Language}
3434

@@ -46,23 +46,29 @@ \subsection*{Error Handling}
4646

4747
\input source_bnf.tex
4848

49-
\input source_1_bnf.tex
49+
\input source_1_bnf_without_import.tex
5050

5151
\newpage
5252

53-
\input source_boolean_operators
54-
5553
\input source_return
5654

55+
\input source_boolean_operators
56+
5757
\input source_names_lang
5858

5959
\input source_numbers
6060

6161
\input source_strings
6262

63+
\input source_comments
64+
6365
\input source_typing
6466

65-
\input source_comments
67+
\section{Standard Libraries}
68+
69+
The following library is always available in this language.
70+
71+
\input source_misc
6672

6773
\input source_js_differences
6874

‎docs/specs/source_2.tex

+14-8
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
\input source_intro.tex
99

10-
\section*{Changes}
10+
\section{Changes}
1111

1212
Compared to Source \S 1, Source \S 2 has the following changes:
1313
\begin{itemize}
@@ -17,27 +17,33 @@ \section*{Changes}
1717

1818
\newpage
1919

20-
\input source_import
21-
2220
\input source_bnf.tex
2321

2422
\input source_2_bnf.tex
2523

26-
\input source_boolean_operators
27-
2824
\input source_return
2925

30-
\input source_names
26+
\input source_import
3127

32-
\input source_lists
28+
\input source_boolean_operators
29+
30+
\input source_names_lang
3331

3432
\input source_numbers
3533

3634
\input source_strings
3735

36+
\input source_comments
37+
3838
\input source_typing
3939

40-
\input source_comments
40+
\section{Standard Libraries}
41+
42+
The following library is always available in this language.
43+
44+
\input source_misc
45+
46+
\input source_lists
4147

4248
\input source_js_differences
4349

‎docs/specs/source_2_lazy.tex

+14-6
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
Source \S 2 Lazy is a lazy-evaluation variant of Source \S 2.
1414

15-
\section*{Changes}
15+
\section{Changes}
1616

1717
Source \S 2 Lazy modifies Source \S 2 by using
1818
lazy evaluation. In
@@ -41,21 +41,29 @@ \section*{Changes}
4141

4242
\input source_2_bnf.tex
4343

44-
\input source_boolean_operators
45-
4644
\input source_return
4745

48-
\input source_names
46+
\input source_import
4947

50-
\input source_lists
48+
\input source_boolean_operators
49+
50+
\input source_names_lang
5151

5252
\input source_numbers
5353

5454
\input source_strings
5555

56+
\input source_comments
57+
5658
\input source_typing
5759

58-
\input source_comments
60+
\section{Standard Libraries}
61+
62+
The following library is always available in this language.
63+
64+
\input source_misc
65+
66+
\input source_lists
5967

6068
\input source_js_differences
6169

‎docs/specs/source_3.tex

+16-12
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
\input source_intro.tex
99

10-
\section*{Changes}
10+
\section{Changes}
1111

1212
Compared to Source \S 2, Source \S 3 has the following changes:
1313
\begin{itemize}
@@ -33,33 +33,37 @@ \section*{Changes}
3333

3434
\newpage
3535

36+
\input source_return
37+
3638
\input source_import
3739

3840
\input source_boolean_operators
3941

4042
\input source_loops
4143

42-
\input source_return
44+
\input source_names_lang
4345

44-
\input source_names
46+
\input source_numbers
4547

46-
\input source_lists
48+
\input source_strings
4749

48-
\input source_pair_mutators
50+
\input source_arrays
4951

50-
\input source_array_support
52+
\input source_comments
5153

52-
\input source_streams
54+
\input source_typing_3
5355

54-
\input source_numbers
56+
\section{Standard Libraries}
5557

56-
\input source_strings
58+
\input source_misc
5759

58-
\input source_arrays
60+
\input source_lists
5961

60-
\input source_typing_3
62+
\input source_pair_mutators
6163

62-
\input source_comments
64+
\input source_array_support
65+
66+
\input source_streams
6367

6468
\input source_js_differences
6569

‎docs/specs/source_3_bnf_without_import.tex

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
\begin{alignat*}{9}
2+
&& \textit{program} &&\quad ::= &\quad && \textit{statement} \ \ldots
3+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/3.1.1.html\#p6}{program}} \\[1mm]
4+
&& \textit{statement} &&\quad ::= &\quad && \textbf{\texttt{const}}\ \textit{name} \
5+
\textbf{\texttt{=}}\ \textit{expression} \ \textbf{\texttt{;}}
6+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.2.html\#p2}{constant declaration}} \\
7+
&& && | &\quad && \textit{let} \ \textbf{\texttt{;}}
8+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/3.1.1.html\#p3}{variable declaration}} \\
9+
&& && | &\quad && \textit{assignment} \ \textbf{\texttt{;}}
10+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/3.1.1.html\#p4}{variable assignment}} \\
11+
&& && | &\quad && \textit{expression} \textbf{\texttt{[}}
12+
\textit{expression} \textbf{\texttt{]}} \
13+
\textbf{\texttt{=}}\ \textit{expression} \ \textbf{\texttt{;}}
14+
&& \textrm{array assignment} \\
15+
&& && | &\quad && \textbf{\texttt{function}}\ \textit{name} \
16+
\textbf{\texttt{(}}\ \textit{parameters} \ \textbf{\texttt{)}}\ \textit{block} \quad
17+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p4}{function declaration}}\\
18+
&& && | &\quad && \textbf{\texttt{return}}\ \textit{expression} \ \textbf{\texttt{;}}
19+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p4}{return statement}}\\
20+
&& && | &\quad && \textit{if-statement} \quad
21+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.3.2.html\#p13}{conditional statement}}\\
22+
&& && | &\quad && \textbf{\texttt{while}}\
23+
\textbf{\texttt{(}}\ \textit{expression} \ \textbf{\texttt{)}} \
24+
\textit{block}
25+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.7}{while loop}}\\
26+
&& && | &\quad && \textbf{\texttt{for}}\ \textbf{\texttt{(}} \
27+
(\ \textit{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.8}{assignment}} \ | \ \textit{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.9}{let}}\ ) \textbf{\texttt{;}} \\
28+
&& && &\quad && \ \ \ \ \ \ \ \ \ \ \textit{expression} \ \textbf{\texttt{;}} \\
29+
&& && &\quad && \ \ \ \ \ \ \ \ \ \ \textit{assignment} \ \textbf{\texttt{)}} \
30+
\textit{block}
31+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.8}{for loop}}\\
32+
&& && | &\quad && \textbf{\texttt{break}}\ \textbf{\texttt{;}}
33+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.7}{break statement}}\\
34+
&& && | &\quad && \textbf{\texttt{continue}}\ \textbf{\texttt{;}}
35+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.7}{continue statement}}\\
36+
&& && | &\quad && \textit{block}
37+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.8.html\#p14}{block statement}}\\
38+
&& && | &\quad && \textit{expression} \ \textbf{\texttt{;}}
39+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p3}{expression statement}} \\[1mm]
40+
&& \textit{parameters} && ::= &\quad && \epsilon\ | \ \textit{name} \
41+
(\ \textbf{\texttt{,}} \ \textit{name}\ )\ \ldots
42+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p4}{function parameters}} \\[1mm]
43+
&& \textit{if-statement} && ::= &\quad && \textbf{\texttt{if}}\
44+
\textbf{\texttt{(}}\ \textit{expression} \ \textbf{\texttt{)}}\
45+
\textit{block} \\
46+
&& && & && \textbf{\texttt{else}}\
47+
(\ \textit{block}
48+
\ | \
49+
\textit{\href{https://source-academy.github.io/sicp/chapters/1.3.3.html\#footnote-1}{if-statement}} \ )
50+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.3.2.html\#p12}{conditional statement}} \\[1mm]
51+
&& \textit{block} && ::= & && \textbf{\texttt{\{}}\ \textit{statement}\ \ldots \ \textbf{\texttt{\}}} \quad
52+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.8.html\#p14}{block statement}} \\[1mm]
53+
&& \textit{let} && ::= &\quad && \textbf{\texttt{let}}\ \textit{name} \
54+
\textbf{\texttt{=}}\ \textit{expression}
55+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/3.1.1.html\#p3}{variable declaration}} \\[1mm]
56+
&& \textit{assignment} && ::= &\quad && \textit{name} \
57+
\textbf{\texttt{=}}\ \textit{expression}
58+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/3.1.1.html\#p4}{variable assignment}} \\[1mm]
59+
&& \textit{expression} && ::= &\quad && \textit{number} && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p3}{primitive number expression}}\\
60+
&& && | &\quad && \textbf{\texttt{true}}\ |\ \textbf{\texttt{false}}
61+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p1}{primitive boolean expression}}\\
62+
&& && | &\quad && \textit{string} && \textrm{\href{https://source-academy.github.io/sicp/chapters/2.3.1.html}{primitive string expression}} \\
63+
&& && | &\quad && \textbf{\texttt{null}}
64+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/2.2.1.html\#p1}{primitive list expression}} \\
65+
&& && | &\quad && \textit{name} && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.2.html}{name expression}} \\
66+
&& && | &\quad && \textit{expression} \ \textit{binary-operator} \
67+
\textit{expression} \qquad
68+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p5}{binary operator combination}} \\
69+
&& && | &\quad && \textit{unary-operator} \
70+
\textit{expression}
71+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{unary operator combination}}\\
72+
&& && | &\quad && \textit{expression} \
73+
\textbf{\texttt{(}}\ \textit{expressions}\
74+
\textbf{\texttt{)}}
75+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p5}{function application}} \\
76+
&& && | &\quad && (\ \textit{name}\ | \
77+
\textbf{\texttt{(}}\ \textit{parameters}\ \textbf{\texttt{)}}\
78+
)\
79+
\texttt{\textbf{=>}}\ \textit{expression}
80+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.3.2.html}{lambda expression (expr. body)}} \\
81+
&& && | &\quad && (\ \textit{name}\ | \
82+
\textbf{\texttt{(}}\ \textit{parameters}\ \textbf{\texttt{)}}\
83+
)\
84+
\texttt{\textbf{=>}}\ \textit{block}
85+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/2.2.4.html\#footnote-3}{lambda expression (block body)}} \\
86+
&& && | &\quad && \textit{expression} \ \textbf{\texttt{?}}\
87+
\textit{expression}
88+
\ \textbf{\texttt{:}}\
89+
\textit{expression}\
90+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p1}{conditional expression}} \\
91+
&& && | &\quad && \textit{expression} \textbf{\texttt{[}}
92+
\textit{expression} \textbf{\texttt{]}}
93+
&& \textrm{array access} \\
94+
&& && | &\quad && \textbf{\texttt{[}}\
95+
\textit{expressions}\
96+
\textbf{\texttt{]}}
97+
&& \textrm{literal array expression}\\
98+
&& && | &\quad && \textbf{\texttt{(}}\ \textit{expression} \
99+
\textbf{\texttt{)}} && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p6}{parenthesised expression}}\\[1mm]
100+
&& \textit{binary-operator} \
101+
&& ::= &\quad && \textbf{\texttt{+}}\ |\ \textbf{\texttt{-}}\ |\ \textbf{\texttt{*}}\ |\ \textbf{\texttt{/}}\ |\ \textbf{\texttt{\%}}\ |\
102+
\textbf{\texttt{===}}\ |\ \textbf{\texttt{!==}}\ \\
103+
&& && | &\quad && \texttt{\textbf{>}}\ |\ \texttt{\textbf{<}}\ |\ \texttt{\textbf{>=}}\ |\ \texttt{\textbf{<=}}\
104+
|\ \textbf{\texttt{\&\&}}\ |\ \texttt{\textbf{||}}
105+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p4}{binary operator}}\\[1mm]
106+
&& \textit{unary-operator}
107+
&& ::= &\quad && \textbf{\texttt{!}}\ |\ \textbf{\texttt{-}}
108+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{unary operator}}\\[1mm]
109+
&& \textit{expressions} && ::= &\quad && \epsilon\ | \ \textit{expression}\ (
110+
\ \textbf{\texttt{,}} \
111+
\textit{expression} \
112+
)\ \ldots
113+
&& \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p5}{argument expressions}}
114+
\end{alignat*}

‎docs/specs/source_3_concurrent.tex

+19-15
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
Source \S 3 Concurrent is a concurrent extension of Source \S 3.
1111

12-
\section*{Changes}
12+
\section{Changes}
1313

1414
Source \S 3 Concurrent modifies Source \S 3 in the following ways:
1515
\begin{itemize}
@@ -29,7 +29,7 @@ \section*{Changes}
2929
\href{https://sicp.comp.nus.edu.sg}{\color{DarkBlue}\emph{Structure and Interpretation
3030
of Computer Programs}, JavaScript Adaptation}.
3131

32-
\section*{Concurrency}
32+
\section{Concurrency}
3333

3434
We specify \emph{interleaving semantics} for Source \S 3 Concurrent.
3535
The effect of executing a Source \S 3 Concurrent program
@@ -54,37 +54,41 @@ \section*{Concurrency}
5454

5555
\newpage
5656

57-
\input source_3_bnf.tex
57+
\input source_3_bnf_without_import.tex
5858

5959
\newpage
6060

61+
\input source_return
62+
6163
\input source_boolean_operators
6264

6365
\input source_loops
6466

65-
\input source_return
67+
\input source_names_lang
6668

67-
\input source_names
69+
\input source_numbers
6870

69-
\input source_concurrency
71+
\input source_strings
7072

71-
\input source_lists
73+
\input source_arrays
7274

73-
\input source_pair_mutators
75+
\input source_comments
7476

75-
\input source_array_support
77+
\input source_typing_3
7678

77-
\input source_streams
79+
\section{Standard Libraries}
7880

79-
\input source_numbers
81+
\input source_misc
8082

81-
\input source_strings
83+
\input source_concurrency
8284

83-
\input source_arrays
85+
\input source_lists
8486

85-
\input source_typing_3
87+
\input source_pair_mutators
8688

87-
\input source_comments
89+
\input source_array_support
90+
91+
\input source_streams
8892

8993
\input source_js_differences
9094

‎docs/specs/source_3_nondet.tex

+20-15
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
Source \S 3 Non-Det is a nondeterministic variant of Source \S 3.
1111

12-
\section*{Changes}
12+
\section{Changes}
1313

1414
Source \S 3 Non-Det modifies Source \S 3 by adding an automatic search mechanism into the language semantics. The language allows programmers to specify \emph{choices} and \emph{requirements}. At runtime, the search mechanism automatically resolves these requirements, and identifies all those choices that satisfy them. \newline
1515

@@ -27,40 +27,45 @@ \section*{Changes}
2727

2828
\newpage
2929

30-
\input source_3_bnf.tex
30+
\input source_3_bnf_without_import.tex
3131

3232
\newpage
3333

34+
\input source_return
35+
36+
\input source_import
37+
3438
\input source_boolean_operators
3539

3640
\input source_loops
3741

38-
\input source_return
42+
\input source_names_lang
3943

40-
\input source_names
44+
\input source_numbers
4145

42-
\input source_nondet
46+
\input source_strings
4347

44-
\input source_lists
48+
\input source_arrays
4549

46-
\input source_pair_mutators
50+
\input source_comments
4751

48-
\input source_array_support
52+
\input source_typing_3
4953

50-
\input source_streams
54+
\section{Standard Libraries}
5155

52-
\input source_numbers
56+
\input source_misc
5357

54-
\input source_strings
58+
\input source_nondet
5559

56-
\input source_arrays
60+
\input source_lists
5761

58-
\input source_typing_3
62+
\input source_pair_mutators
5963

60-
\input source_comments
64+
\input source_array_support
6165

62-
\input source_js_differences
66+
\input source_streams
6367

68+
\input source_js_differences
6469

6570
\newpage
6671

‎docs/specs/source_4.tex

+19-13
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
\input source_intro.tex
99

10-
\section*{Changes}
10+
\section{Changes}
1111

1212
Compared to Source \S 3, Source \S 4 has the following changes:
1313
\begin{itemize}
@@ -23,35 +23,41 @@ \section*{Changes}
2323

2424
\newpage
2525

26+
\input source_return
27+
2628
\input source_import
2729

2830
\input source_boolean_operators
2931

3032
\input source_loops
3133

32-
\input source_return
34+
\input source_names_lang
3335

34-
\input source_names
36+
\input source_numbers
3537

36-
\input source_lists
38+
\input source_strings
3739

38-
\input source_pair_mutators
40+
\input source_arrays
3941

40-
\input source_array_support
42+
\input source_comments
4143

42-
\input source_streams
44+
\input source_typing_3
4345

44-
\input source_numbers
46+
\section{Standard Libraries}
4547

46-
\input source_strings
48+
The following libraries are always available in this language.
4749

48-
\input source_arrays
50+
\input source_misc
4951

50-
\input source_typing_3
52+
\input source_lists
5153

52-
\input source_interpreter
54+
\input source_pair_mutators
5355

54-
\input source_comments
56+
\input source_array_support
57+
58+
\input source_streams
59+
60+
\input source_interpreter
5561

5662
\input source_js_differences
5763

‎docs/specs/source_4_gpu.tex

+21-13
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
\input source_intro.tex
99

10-
\section*{Changes}
10+
\section{Changes}
1111

1212
Source \S 4 GPU allows for Source programs to be accelerated on the GPU if certain conditions are met.
1313
The exact specifications for this is outlined on page \pageref{gpu_supp}. Source \S 4 GPU defines a formal specification
@@ -21,33 +21,41 @@ \section*{Changes}
2121

2222
\newpage
2323

24-
\input source_boolean_operators
25-
26-
\input source_loops
27-
2824
\input source_return
2925

30-
\input source_names
26+
\input source_import
3127

32-
\input source_lists
33-
34-
\input source_pair_mutators
28+
\input source_boolean_operators
3529

36-
\input source_array_support
30+
\input source_loops
3731

38-
\input source_streams
32+
\input source_names_lang
3933

4034
\input source_numbers
4135

4236
\input source_strings
4337

4438
\input source_arrays
4539

40+
\input source_comments
41+
4642
\input source_typing_3
4743

48-
\input source_interpreter
44+
\section{Standard Libraries}
4945

50-
\input source_comments
46+
The following libraries are always available in this language.
47+
48+
\input source_misc
49+
50+
\input source_lists
51+
52+
\input source_pair_mutators
53+
54+
\input source_array_support
55+
56+
\input source_streams
57+
58+
\input source_interpreter
5159

5260
\input source_js_differences
5361

‎docs/specs/source_arrays.tex

+1-21
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,7 @@
1-
\section*{Arrays}
1+
\subsection*{Arrays}
22

33
Arrays in Source are created using literal array expressions:
44
\begin{lstlisting}
55
let my_array_1 = [];
66
let my_array_2 = [42, 71, 13];
77
\end{lstlisting}
8-
Arrays in Source are limited to integers as keys.
9-
In statements like
10-
\begin{lstlisting}
11-
a[i];
12-
a[j] = v;
13-
\end{lstlisting}
14-
the values \lstinline{i} and \lstinline{j} must be integers if \lstinline{a} is an array.
15-
16-
Note that pairs in Source are represented by arrays with two elements. Therefore,
17-
\begin{lstlisting}
18-
is_pair([1, 2]);
19-
\end{lstlisting}
20-
and
21-
\begin{lstlisting}
22-
equal(pair(1, 2), [1, 2]);
23-
\end{lstlisting}
24-
evaluate to \texttt{true}.
25-
26-
Access of an array with an integer index to which no prior assignment has been
27-
made on the array, returns \texttt{undefined}.

‎docs/specs/source_bnf.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\section*{Programs}
1+
\section{Syntax}
22

33
A Source program is a \emph{program}, defined using Backus-Naur Form\footnote{
44
We adopt Henry Ledgard's BNF variant that he described in

‎docs/specs/source_boolean_operators.tex

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
\section*{Binary boolean operators}
1+
\subsection*{Binary boolean operators}
22

3-
\subsection*{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{Conjunction}}
3+
\subsubsection*{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{Conjunction}}
44

55
\[
66
\textit{expression}_1 \ \textbf{\texttt{\&\&}} \ \textit{expression}_2
@@ -10,7 +10,7 @@ \subsection*{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4
1010
\textit{expression}_1 \ \textbf{\texttt{?}} \ \textit{expression}_2 \ \textbf{\texttt{:}}\ \textbf{\texttt{false}}
1111
\]
1212

13-
\subsection*{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{Disjunction}}
13+
\subsubsection*{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{Disjunction}}
1414

1515
\[
1616
\textit{expression}_1 \ \textbf{\texttt{||}} \ \textit{expression}_2

‎docs/specs/source_comments.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\section*{\href{https://source-academy.github.io/sicp/chapters/2.2.3.html\#footnote-8}{Comments}}
1+
\subsection*{\href{https://source-academy.github.io/sicp/chapters/2.2.3.html\#footnote-8}{Comments}}
22

33
In Source, any sequence of characters between ``\texttt{/*}'' and
44
the next ``\texttt{*/}'' is ignored.

‎docs/specs/source_header.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
\usepackage[T1]{fontenc}
1010

11-
\usepackage[paper=portrait,pagesize]{typearea}
11+
\usepackage[paper=210mm:297mm]{typearea}
1212

1313
\usepackage{listings}
1414

‎docs/specs/source_import.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\section*{Import directives}
1+
\subsection*{Import directives}
22

33
Import directives allow programs to import values from modules and bind them to names, whose scope
44
is the entire program in which the import directive occurs. All names that appear in import directives

‎docs/specs/source_interpreter.tex

+2-1
Original file line numberDiff line numberDiff line change
@@ -143,5 +143,6 @@ \section*{Interpreter Support}
143143

144144

145145
\newpage
146-
\KOMAoptions{paper=portrait,pagesize}
146+
\KOMAoptions{paper=portrait}
147147
\recalctypearea
148+

‎docs/specs/source_loops.tex

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
\section*{Loops}
1+
\subsection*{Loops}
22

3-
\subsection*{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.7}{while-loops}}
3+
\subsubsection*{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.7}{while-loops}}
44

55
Roughly speaking, while loops are seen as abbreviations for function applications as follows:
66

@@ -30,7 +30,7 @@ \subsection*{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex
3030
}
3131
\end{lstlisting}
3232
33-
\subsection*{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.8}{Simple for-loops}}
33+
\subsubsection*{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.8}{Simple for-loops}}
3434
3535
\[\textbf{\texttt{for}}\ \textbf{\texttt{(}} \
3636
\textit{assignment}_1 \textbf{\texttt{;}}
@@ -50,7 +50,7 @@ \subsection*{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex
5050
\end{minipage}
5151
\end{center}
5252
53-
\subsection*{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.9}{for-loops with loop control variable}}
53+
\subsubsection*{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex_4.9}{for-loops with loop control variable}}
5454
5555
\[\textbf{\texttt{for}}\ \textbf{\texttt{(}} \
5656
\textbf{\texttt{let}}\ \textit{name}\ \texttt{=}\
@@ -77,7 +77,7 @@ \subsection*{\href{https://source-academy.github.io/sicp/chapters/4.1.2.html\#ex
7777
7878
\end{center}
7979
80-
\subsection*{Return values, \lstinline{break} and \lstinline{continue}}
80+
\subsubsection*{Return values, \lstinline{break} and \lstinline{continue}}
8181
8282
Contrary to the simplified explanation above, \lstinline{while} and \lstinline{for} loops return
8383
the value of their last loop execution, or \lstinline{undefined} if there is no loop execution.

‎docs/specs/source_names.tex ‎docs/specs/source_misc.tex

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
\input source_names_lang
1+
\subsection*{MISC Library}
2+
23

34
In addition to names that
45
are declared using \texttt{\textbf{const}}, \texttt{\textbf{function}},

‎docs/specs/source_names_lang.tex

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\section*{Names}
1+
\subsection*{Names}
22

33
Names\footnote{
44
In
@@ -17,7 +17,7 @@ \section*{Names}
1717
}. Reserved words\footnote{
1818
By \emph{Reserved word} we mean any of:
1919
$\textbf{\texttt{break}}$, $\textbf{\texttt{case}}$, $\textbf{\texttt{catch}}$, $\textbf{\texttt{continue}}$, $\textbf{\texttt{debugger}}$, $\textbf{\texttt{default}}$, $\textbf{\texttt{delete}}$, $\textbf{\texttt{do}}$, $\textbf{\texttt{else}}$, $\textbf{\texttt{finally}}$, $\textbf{\texttt{for}}$, $\textbf{\texttt{function}}$, $\textbf{\texttt{if}}$, $\textbf{\texttt{in}}$, $\textbf{\texttt{instanceof}}$, $\textbf{\texttt{new}}$, $\textbf{\texttt{return}}$, $\textbf{\texttt{switch}}$, $\textbf{\texttt{this}}$, $\textbf{\texttt{throw}}$, $\textbf{\texttt{try}}$, $\textbf{\texttt{typeof}}$, $\textbf{\texttt{var}}$, $\textbf{\texttt{void}}$, $\textbf{\texttt{while}}$, $\textbf{\texttt{with}}$, $\textbf{\texttt{class}}$, $\textbf{\texttt{const}}$, $\textbf{\texttt{enum}}$, $\textbf{\texttt{export}}$, $\textbf{\texttt{extends}}$, $\textbf{\texttt{import}}$, $\textbf{\texttt{super}}$, $\textbf{\texttt{implements}}$, $\textbf{\texttt{interface}}$, $\textbf{\texttt{let}}$, $\textbf{\texttt{package}}$, $\textbf{\texttt{private}}$, $\textbf{\texttt{protected}}$, $\textbf{\texttt{public}}$, $\textbf{\texttt{static}}$, $\textbf{\texttt{yield}}$, $\textbf{\texttt{null}}$, $\textbf{\texttt{true}}$, $\textbf{\texttt{false}}$.
20-
} such as keywords are not allowed as names.
20+
} are not allowed as names.
2121

2222
Valid names are \verb@x@, \verb@_45@, \verb@$$@ and $\mathtt{\pi}$,
2323
but always keep in mind that programming is communicating and that the familiarity of the

‎docs/specs/source_numbers.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\section*{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p3}{Numbers}}
1+
\subsection*{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p3}{Numbers}}
22

33
We use decimal notation for numbers, with an optional decimal dot. ``Scientific notation''
44
(multiplying the number with $10^x$) is indicated with the letter \texttt{e}, followed

‎docs/specs/source_return.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\section*{Restrictions}
1+
\subsection*{Restrictions}
22

33
\begin{itemize}
44
\item Return statements are only allowed in bodies of functions.

‎docs/specs/source_strings.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\section*{\href{https://source-academy.github.io/sicp/chapters/2.3.1.html}{Strings}}
1+
\subsection*{\href{https://source-academy.github.io/sicp/chapters/2.3.1.html}{Strings}}
22

33
Strings are of the form \texttt{"}$ \textit{double-quote-characters} $\texttt{"},
44
where $\textit{double-quote-characters}$ is a possibly empty sequence of characters without

‎docs/specs/source_typing.tex

+8-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11

2-
\section*{Typing}
2+
\section{Typing}
33

4-
Expressions evaluate to numbers, boolean values, strings or function values.
4+
Expressions evaluate to numbers, boolean values, strings or function values. Implementations
5+
of Source generate error messages when unexpected values are used as follows.
56

67
Only function values can be applied using the syntax:
78

@@ -12,8 +13,12 @@ \section*{Typing}
1213
\texttt{\textbf{)}}\\
1314
\end{eqnarray*}
1415

16+
For compound functions, implementations need to check that the number of \textit{expressions}
17+
matches the number of parameters.
18+
1519
The following table specifies what arguments Source's operators
16-
take and what results they return.
20+
take and what results they return. Implementations need to check the types of arguments and
21+
generate an error message when the types do not match.
1722

1823
\begin{center}
1924
\begin{tabular}{c|c|c|c}

‎docs/specs/source_typing_3.tex

+26-4
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11

2-
\section*{Typing}
2+
\section{Dynamic Type Checking}
33

4-
Expressions evaluate to numbers, boolean values, strings or function values.
4+
Expressions evaluate to numbers, boolean values, strings, arrays or function values. Implementations
5+
of Source generate error messages when unexpected values are used as follows.
56

67
Only function values can be applied using the syntax:
78

@@ -12,8 +13,12 @@ \section*{Typing}
1213
\texttt{\textbf{)}}\\
1314
\end{eqnarray*}
1415

16+
For compound functions, implementations need to check that the number of \textit{expressions}
17+
matches the number of parameters.
18+
1519
The following table specifies what arguments Source's operators
16-
take and what results they return.
20+
take and what results they return. Implementations need to check the types of arguments and
21+
generate an error message when the types do not match.
1722

1823
\begin{center}
1924
\begin{tabular}{c|c|c|c}
@@ -44,4 +49,21 @@ \section*{Typing}
4449
Preceding \texttt{\textbf{?}} and following \texttt{\textbf{if}}, Source only allows
4550
boolean expressions.
4651

47-
Only numbers are allowed in the key of member expressions of arrays (\texttt{\textbf{arr[key]}}).
52+
In array access \texttt{\textbf{arr[key]}},
53+
only arrays are allowed as \texttt{\textbf{arr}} and
54+
only integers are allowed as \texttt{\textbf{key}}.
55+
56+
Array indices in Source are limited to integers $i$ in the range $0 \le i < 2^{32} - 1$.
57+
58+
Pairs in Source are represented by arrays with two elements. Therefore,
59+
\begin{lstlisting}
60+
is_pair([1, 2]);
61+
\end{lstlisting}
62+
and
63+
\begin{lstlisting}
64+
equal(pair(1, 2), [1, 2]);
65+
\end{lstlisting}
66+
evaluate to \texttt{true}.
67+
68+
Access of an array with an array index to which no prior assignment has been
69+
made on the array returns \texttt{undefined}.

0 commit comments

Comments
 (0)
Please sign in to comment.