Skip to content

Library documentation #271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 20 commits into from
Jul 30, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,7 @@ node_modules
*.js
*.map
dist/

# emacs backup files

*~
22 changes: 22 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -53,3 +53,25 @@ including specifics and correction guides, should be left to elaborate().

Please remember to write test cases to reflect your added functionalities. The god of this repository is self-professed
to be very particular about test cases.

Documentation
-------------

Documentation on Source §x is generated from LaTeX sources in folder ``doc``.
Currently the documents are generated as follows:
``
cd doc; make
``

Documentation on the Source libraries are generated from inline documentation
in the library sources. The libraries are in repository ``cadet-frontend``, which
is assumed to be located in ``../cadet-frontend``, from the root of this repo.
The documentation is generated as follows:
``
yarn run jsdoc
``
This command makes the documentation available in folder
``
doc/jsdoc/libraries/
``

1 change: 1 addition & 0 deletions doc/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@
*.pdf
*.out
*~
Source
55 changes: 36 additions & 19 deletions doc/README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,39 @@
### Naming
- The official specifications for Source § X is `source_X.pdf`.
- Other `.tex` files are used as imports within the specs.
- `source_week_X.pdf` is an *internal reference* for the staff, to aid with discussion groups.
Source is a family of languages, designed for the textbook
<a href="https://sicp.comp.nus.edu.sg">Structure and Interpretation
of Computer Programs, JavaScript Adaptation</a> (SICP JS). The languages are
called Source §1, Source §2, Source §3 and Source §4.
corresponding to the respective chapters 1, 2, 3 and 4 of the
textbook. Each previous Source language is a sublanguage of the
next, and all Source languages are sublanguages of JavaScript.
This webpage contains the description of the Source languages
and the libraries they
come with.

### Generating PDFs
Required for making the documents is a LaTeX installation.
## <a href="source_1/">Source §1</a>

## <a href="source_2/">Source §2</a>

Just try
make
in order to make the four documents
source_1.pdf
source_2.pdf
source_3.pdf
source_4.pdf
source_styleguide.pdf
## <a href="source_3/">Source §3</a>

If you get an error, try
touch *.tex
and try
make
again.
## <a href="source_4/">Source §4</a>

## <a href="External libraries/">External Libraries</a>

The <a href="https://sourceacademy.nus.edu.sg">Source Academy</a>,
a learning environment that uses SICP JS and Source, comes with the following
<a href="External libraries/">external libraries</a>:

<ul>
<li>
<a href="RUNES/index.html">RUNES</a>: programming with rune graphics
</li>
<li>
<a href="CURVES/index.html">CURVES</a>: programming with curve graphics
</li>
<li>
<a href="SOUNDS/index.html">SOUNDS</a>: sound processing
</li>
<li>
<a href="BINARYTREES/index.html">BINARYTREES</a>: binary trees
</li>
</ul>
147 changes: 147 additions & 0 deletions doc/README_1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
Source §1 is a small programming language, designed for the first chapter
of the textbook
<a href="https://sicp.comp.nus.edu.sg">Structure and Interpretation
of Computer Programs, JavaScript Adaptation</a> (SICP JS).

## What names are predeclared in Source §1?

On the right, you see all predeclared names of Source §1, in alphabetical
order. Click on a name to see how it is defined and used.
These names come in two groups:
<ul>
<li>
<a href="../MISC/index.html">MISC</a>: Miscellaneous constants and functions
</li>
<li>
<a href="../MATH/index.html">MATH</a>: Mathematical constants and functions
</li>
</ul>
In addition,
<a href="https://sicp.comp.nus.edu.sg/chapters/33">section 2.2.4 SICP JS</a> makes
use of <a href="../RUNES/index.html">RUNES</a>, a library for runes graphics.

## What can you do in Source §1?

You can use all features that are introduced in
<a href="https://sicp.comp.nus.edu.sg/chapters/1">chapter 1</a> of the
textbook. Below is the list of features, each with a link to the
textbook section that introduces it and a small example.

### Literal values

Literal values are simple expressions that directly evaluate to values. These
include numbers in the usual decimal notation, the two boolean values
`true` and `false`, and the predeclared names
`NaN`, `Infinity` and `undefined`.
More on literal values in <a href="https://sicp.comp.nus.edu.sg/chapters/2">section
1.1 The Elements of Programming</a> of the textbook.

### Constant declarations

Constant declarations are done in Source with <PRE><CODE>const my_name = x + 2;</CODE></PRE>
Here the name `my_name` gets declared within the surrounding block,
and refers to the result of evaluating `x + 2` in the rest of the block.
You can read more about the <EM>scope of names</EM> in
<a href="https://sicp.comp.nus.edu.sg/chapters/10">section 1.1.8
Functions as Black-Box Abstractions</a>.

### Conditional statements and conditional expressions

Within expressions, you can let a <EM>predicate</EM> determine whether
a <EM>consequent expression</EM>
gets evaluated or an <EM>alternative expression</EM>. This is done by writing,
for example
<PRE><CODE>return p(x) ? 7 : f(y);</CODE></PRE>
Read more on conditional expressions in
<a href="https://sicp.comp.nus.edu.sg/chapters/8">section 1.1.6
Conditional Expressions and Predicates</a>.
<EM>Conditional evaluation</EM> is also possible within statements, for
example the body of a function declaration. For that, you can use <EM>conditional
statements</EM>, for example:<PRE><CODE>if (p(x)) {
return 7;
} else {
return f(y);
}</CODE></PRE>
Read about <EM>conditional statements</EM> in
<a href="https://sicp.comp.nus.edu.sg/chapters/20">section 1.3.2
Function Definition Expressions</a>.

### Function declarations and function definitions

A function declaration is a statement that declares a name and binds it
to a function. For example
<PRE><CODE>function square(x) {
return x * x;
}</CODE>
</PRE>
declares the name `square` and binds it to a squaring function, so that it can be applied
as in `square(5);`. You can read about function declaration statements in textbook
<a href="https://sicp.comp.nus.edu.sg/chapters/6">section 1.1.4 Functions</a>.

Sometimes, it's not necessary to give a name to a function: You may
want to create a function only to pass it to some other function as argument.
For that, Source
supports function definition expressions. For example
<PRE><CODE>(x => x * x)(3); // returns 9</CODE>
</PRE>
creates a square function just like the function declaration above,
but does not give it a name.
Its only purpose it to be applied to the number 3. See also
textbook
<a href="https://sicp.comp.nus.edu.sg/chapters/20">section 1.3.2 Function Definition Expressions</a>.

### Blocks

Blocks make up the bodies of functions and the consequent and alternative statements of
conditional statements. You can use blocks also elsewhere in your program, if you
want to declare constants local to a specific scope. For example in this program
<PRE><CODE>const a = 1;
{
const a = 2;
display(a);
}
display(a);</CODE>
</PRE>
the first application of `display` shows the value 2, because the
declaration <B>const</B> `a = 2;` re-declares the constant `a`.
However, the second application
of `display` shows the value 1, because
the declaration <B>const</B> `a = 2;` is limited in scope by its surrounding block.
You can read more about <EM>blocks</EM> in
<a href="https://sicp.comp.nus.edu.sg/chapters/10">section 1.1.8
Functions as Black-Box Abstractions</a>.

### Boolean operators

Boolean operators in Source have a special meaning. Usually, an operator combination
evaluates all its arguments and then applies the operation to which the operator refers.
For example, `(2 * 3) + (4 * 5)` evaluates `2 * 3` and `4 * 5` first, before the addition
is carried out. However, the operator `&&` works differently. An expression
`e1 && e2` should be seen as an abbreviation for `e1 ? e2 : false`. The expression
`e2` only gets evaluated if `e1` evaluates to `true`. The behaviour of `||` is similar:
`e1 || e2` should be seen as an abbreviation for `e1 ? true : e2`. More on these
two boolean operators in textbook
<a href="https://sicp.comp.nus.edu.sg/chapters/8">section 1.1.6 Conditional
Expressions and Predicates</a>.

### Sequences

A program or the body of a block does not need to consist of a single statement.
You can write multiple statements in a row. In the REPL ("Read-Eval-Print-Loop")
of a Source implementation, you can write
<PRE><CODE>cube(7);
square(5);</CODE></PRE>
The statements in such a sequence are evaluated in the given order. The
result of evaluating the sequence is the result of evaluating the last
statement in the sequence, in this case `square(5);`.
Read more about sequences in
<a href="https://sicp.comp.nus.edu.sg/chapters/4">section 1.1.2
Naming and the Environment</a> of the textbook.

## You want the definitive specs?

For our development team, we are maintaining a definitive description
of the language, called the
<a href="../source_1.pdf">Specification of Source §1</a>. Feel free to
take a peek.

66 changes: 66 additions & 0 deletions doc/README_2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
Source §2 is a small programming language, designed for the second chapter
of the textbook
<a href="https://sicp.comp.nus.edu.sg">Structure and Interpretation
of Computer Programs, JavaScript Adaptation</a> (SICP JS).

## What names are predeclared in Source §2?

On the right, you see all predeclared names of Source §2, in alphabetical
order. Click on a name to see how it is used. They come in these three groups:
<ul>
<li>
<a href="../MISC/">MISC</a>: Miscellaneous constants and functions
</li>
<li>
<a href="../MATH/">MATH</a>: Mathematical constants and functions
</li>
<li>
<a href="../LISTS/">LISTS</a>: Support for lists
</li>
</ul>

The <a href="https://sourceacademy.nus.edu.sg">Source Academy</a>,
a learning environment that uses SICP JS and Source, comes with the following
<a href="External libraries/">external libraries</a>:
<ul>
<li>
<a href="../RUNES/index.html">RUNES</a>: Library for runes graphics
</li>
<li>
<a href="../CURVES/index.html">CURVES</a>: Library for curve graphics
</li>
<li>
<a href="../SOUNDS/index.html">SOUNDS</a>: Library for sound processing
</li>
<li>
<a href="../BINARYTREES/index.html">BINARYTREES</a>: Library for binary trees
</li>
</ul>

## What can you do in Source §2?

You can use all features of
<a href="../Source §1/">Source §1</a> and all
features that are introduced in
<a href="https://sicp.comp.nus.edu.sg/chapters/23">chapter 2</a> of the
textbook.
Below are the features that Source §2 adds to Source §1.

### The empty list `null`

Source §2 provides a new primitive value, `null`, that serves as empty list.

### The LIST functions

To work with lists, you can use the functions in the
<a href="../LISTS/">LISTS</a> group of predeclared functions, already mentioned
above.

## You want the definitive specs?

For our development team, we are maintaining a definitive description
of the language, called the
<a href="../source_2.pdf">Specification of Source §2</a>. Feel free to
take a peek!


Loading