Merge more runnable code-adjacent features (Together-Java#29)

* more sections

* First feedback round

* Update prelude.md

* ...

* Spelling fix

Co-Authored-By: Firas Regaieg <[email protected]>

* Arguments chapter

* More Challenges

* Run prettier

* user input

* October 14th, Together-Java#1

* Array challenges

* Delete challenges

* Null

* ...

* Update null_as_absence.md

* Delete out.json

* Fix quotes

* Add first no_runs

* Fix number example

---------

Co-authored-by: Firas Regaieg <[email protected]>

README.md

@@ -6,7 +6,7 @@
 
 Book teaching how to write modern and effective Java. It is maintained by the community, anyone can contribute.
 
-Feel free to join our [discord server](https://discord.com/invite/XXFUXzK)
+Feel free to join our [discord server](https://discord.gg/together-java-272761734820003841)
 if you have any questions, or require assistance with the project. :relaxed:
 
 ## Getting started

book.toml

@@ -13,8 +13,8 @@ additional-css = ["ferris.css"]
 additional-js = ["ferris.js"]
 
 [output.html.fold]
-enable = true    # whether or not to enable section folding
-level = 0         # the depth to start folding
+enable = true # whether or not to enable section folding
+level = 0     # the depth to start folding
 
 [preprocessor.features]
 command = "python3 features.py"
@@ -29,3 +29,5 @@ java_21 = false
 [output.html.playground]
 editable = true
 
+[output.html.code.hidelines]
+java = "~"

features.py

@@ -49,9 +49,6 @@ def preprocess_section(context, section):
 
     json_input = json.load(sys.stdin)
     context, book = json_input
-
-    with open("out.json", "w") as f:
-        json.dump(json_input, f)
 
     for section in book["sections"]:
         preprocess_section(context, section)

ferris.js

@@ -5,7 +5,7 @@ var ferrisTypes = [
     },
     {
       attr: 'panics',
-      title: 'This code panics!'
+      title: 'This code will crash!'
     },
     {
       attr: 'not_desired_behavior',

src/SUMMARY.md

@@ -95,14 +95,17 @@
 # Control Flow I
 
 - [Branching Paths](./branching_paths.md)
+
   - [If](./branching_logic/if.md)
-  - [Else](./branching_logic/else.md)
   - [Nested Ifs](./branching_logic/nested_ifs.md)
+  - [Else](./branching_logic/else.md)
   - [Else If](./branching_logic/else_if.md)
   - [Relation to Delayed Assignment](./branching_logic/relation_to_delayed_assignment.md)
+  - [Scoped Variables](./branching_logic/scoped_variables.md)
   - [Conditional Operator](./branching_logic/conditional_operator.md)
   - [Boolean Expressions](./branching_logic/boolean_expressions.md)
   - [Challenges](./branching_logic/challenges.md)
+
 - [Loops](./loops.md)
   - [While](./loops/while.md)
   - [Endless Loops](./loops/endless_loops.md)
@@ -164,11 +167,10 @@
   - [Declaration](./methods/declaration.md)
   - [Invocation](./methods/invocation.md)
   - [Scope](./methods/scope.md)
-  - [Return](./methods/return.md)
-  - [Unreachable Statements](./methods/unreachable_statements.md)
   - [main](./methods/main.md)
   - [Challenges](./methods/challenges.md)
 - [Arguments](./arguments.md)
+
   - [Declaration](./arguments/declaration.md)
   - [Invocation with Arguments](./arguments/invocation_with_arguments.md)
   - [Reassignment](./arguments/reassignment.md)
@@ -177,22 +179,22 @@
   - [Overloading](./arguments/overloading.md)
   - [Inferred Types](./arguments/inferred_types.md)
   - [Challenges](./arguments/challenges.md)
-- [Return Values](./return_values.md)
-  - [void](./return_values/void.md)
+
+- [Return](./return_values.md)
+  - [Return Values](./return_values/return_values.md)
   - [Conversion](./return_values/conversion.md)
+  - [void](./return_values/void.md)
+  - [Unreachable Statements](./return_values/unreachable_statements.md)
   - [Pure Functions](./return_values/pure_functions.md)
   - [Impure Functions](./return_values/impure_functions.md)
 
-# User Input
-
-- [User Input](./user_input.md)
-
 # Data Types III
 
 - [Identity Types](./identity_types.md)
   - [Comparison with ==](./identity_types/comparison_with_equalsequals.md)
 - [Primitive Types](./primitive_types.md)
 - [null](./null.md)
+  - [Null as Absence](./null/null_as_absence.md)
   - [Checking for null](./null/checking_for_null.md)
   - [Field Access](./null/field_access.md)
   - [Instance Methods](./null/instance_methods.md)
@@ -205,7 +207,7 @@
   - [Unboxing Conversion](./boxed_primitives/unboxing_conversion.md)
   - [Boxing Conversion](./boxed_primitives/boxing_conversion.md)
   - [Arrays of Boxed Primitives](./boxed_primitives/arrays_of_boxed_primitives.md)
-  - [Challenges](./arguments/challenges.md)
+  - [Challenges](./boxed_primitives/challenges.md)
 - [Arrays II](./arrays_ii.md)
   - [Default Values](./arrays_ii/default_values.md)
   - [Populate Array]()

src/arguments/final_arguments.md

@@ -32,6 +32,4 @@ This has the same use as regular final variables. If there are lots of lines
 of code where a variable might be reassigned, it can be useful to not have
 to read all that code to know that it does happen.[^opinion]
 
-[^opinion]:
-    Adding `final` to all arguments can make it harder to read the code, simply
-    because of visual noise.
+[^opinion]: Adding `final` to all arguments can make it harder to read the code, simply because of visual noise.

src/arguments/overloading.md

@@ -34,6 +34,4 @@ void main() {
 When there are multiple methods that have the same name but take different arguments,
 those methods are considered "overloads" of eachother[^overload]
 
-[^overload]:
-    "Overloading" in this context means when one word has more than
-    one possible meaning depending on how it is used. Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.
+[^overload]: "Overloading" in this context means when one word has more than one possible meaning depending on how it is used. Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

src/arrays/array_initializers.md

@@ -21,6 +21,4 @@ int[] numbers = { 1, two, two + 1 }
 
 We call them array initializers because you use them to give an initial value to an array.[^pattern]
 
-[^pattern]:
-    You may be noticing a pattern. Confusing sounding names are often kinda "obvious"
-    with enough context.
+[^pattern]: You may be noticing a pattern. Confusing sounding names are often kinda "obvious" with enough context.

src/arrays/challenges.md

@@ -6,3 +6,78 @@ Remember the rules for this are
 - Try not to give up until you've given it a solid attempt
 
 ## Challenge 1
+
+Edit the following program so that the output is zero.
+
+```java
+void main() {
+    // Only change this line
+    String[] words = { "Sam", "I", "Am" };
+    System.out.println(array.length);
+}
+```
+
+## Challenge 2
+
+Using only `System.out.println` and array accesses,
+print `hello world` to the screen.
+
+```java
+void main() {
+    char[] letters = {
+        ' ',
+        'h',
+        'e',
+        'l',
+        'o',
+        'w',
+        'r',
+        'd'
+    };
+
+    // Your code here
+}
+```
+
+## Challenge 3
+
+Without editing either the array declaration or the loop at the bottom,
+make the output of this program `0`.
+
+```java
+void main() {
+    final int numbers = { 1, 2, 3, 4 };
+
+    // -----------
+    // YOUR CODE HERE
+
+
+    // -----------
+    int total = 0;
+    int index = 0;
+    while (index < numbers.length) {
+        total += numbers[index];
+        index += 1;
+    }
+    System.out.println(total);
+}
+```
+
+## Challenge 4
+
+Make this program output `bulbasaur` without changing anything
+above or below the marked areas.
+
+```java
+void main() {
+    char[] name = { 'b', 'u', 'l', 'b' };
+
+    // -----------
+    // YOUR CODE HERE
+
+
+    // -----------
+    char[] toPrint = name;
+    System.out.println(toPrint);
+}
+```

src/arrays/printing_the_contents_of_an_array.md

@@ -48,10 +48,5 @@ while (index < factions.length) {
 }
 ```
 
-[^gibberish]:
-    What `[I@5a07e868` and co. mean isn't really important. Try not to
-    get too distracted by it.
-
-[^future]:
-    Later on, there will be easier ways to do this sort of inspection. This is just the
-    one I can demonstrate now.
+[^gibberish]: What `[I@5a07e868` and co. mean isn't really important. Try not to get too distracted by it.
+[^future]: Later on, there will be easier ways to do this sort of inspection. This is just the one I can demonstrate now.

src/arrays/set_individual_elements.md

@@ -39,6 +39,4 @@ String[] response = { "sustained" };
 response[-1] = "not";
 ```
 
-[^strings]:
-    You cannot change the contents of a `String` like you would an array. This is one of the biggest
-    differences between a `String` and a `char[]`.
+[^strings]: You cannot change the contents of a `String` like you would an array. This is one of the biggest differences between a `String` and a `char[]`.

src/branching_logic/conditional_operator.md

@@ -19,6 +19,4 @@ and then a value to use when that condition evaluates to `false`.
 CONDITION ? WHEN_TRUE : WHEN_FALSE
 ```
 
-[^ternary]:
-    Some people will call this a ternary expression. Ternary meaning "three things."
-    Same idea as tres leches.
+[^ternary]: Some people will call this a ternary expression. Ternary meaning "three things." Same idea as tres leches.

src/branching_logic/scoped_variables.md

@@ -0,0 +1,37 @@
+# Scoped Variables
+
+If you make a variable declaration inside of an `if` or an `else` block,
+that declaration will be "scoped" to the block.
+
+```java
+int age = 5;
+
+if (age == 5) {
+    int nextAge = age + 1;
+    System.out.println(nextAge);
+}
+
+// If you uncomment this line, there will be an issue
+// `nextAge` is not available to the scope outside of the `if`
+// System.out.println(nextAge);
+```
+
+This scoping applies even if all branches declare the same variable
+within their logic.
+
+```java
+int age = 22;
+
+if (age > 25) {
+    String message = "You might be able to rent a car";
+}
+else {
+    String message = "You cannot rent a car!";
+}
+
+// This will not work, because although `message` is declared
+// in all branches, it is not declared in the "outer scope"
+System.out.println(message);
+```
+
+This is why you will sometimes need to use delayed assignment.

src/first_steps.md

@@ -31,7 +31,7 @@ Its a tradition for this to be your first program in any language.
 We aren't quite at the point where I can explain what `void main()` means, but
 all you need to know for now is that it is what Java looks for to know where to start the program.
 
-```java
+```java,no_run
 void main() {
     < WRITE YOUR CODE HERE >
 }
@@ -42,15 +42,15 @@ void main() {
 Unfortunately, for reasons that are impossible to explain with the context you have at this point,
 half of this probably reads as cryptic nonsense.
 
-```java
+```java,no_run
 public class Main {
     public static void main(String[] args) {
 ```
 
 I don't _want_ it to stay cryptic nonsense, but until we get there all you truly need to know
 is that Java uses all of that to know where to start the program.
 
-```java
+```java,no_run
 public class Main {
     public static void main(String[] args) {
         < WRITE YOUR CODE HERE >
@@ -62,7 +62,7 @@ public class Main {
 
 So for all intents and purposes, this is the whole program.
 
-```java
+```java,no_run
 System.out.println("Hello, World!");
 ```
 
@@ -72,7 +72,7 @@ This bit of magic here - `System.out.println` - is a "statement" that "prints" t
 
 If you were to replace it with `System.out.print`, then the output would lack that new line. This makes the following program be functionally identical to the first.
 
-```java
+```java,no_run
 System.out.print("Hello, ");
 System.out.print("World");
 System.out.println("!");
@@ -109,4 +109,4 @@ public class Main {
 You should get in the habit of, whenever you see some bit of code, trying to physically type it out, run it,
 tweak it, and play with it.
 
-So try playing around with this program. If you are not actively engaging then the whole thing is a bit of a wash.
+So try playing around with this program. If you actively engage then you will retain information better.

src/first_steps/challenges.md

@@ -12,7 +12,7 @@ The rules for this are
 
 Write a program that prints your name twice. So if your name is "Jasmine", the output of the program should be this.
 
-```text
+```text,no_run
 Jasmine
 Jasmine
 ```
@@ -63,7 +63,7 @@ How could you use that error to figure out where you might have forgotten to put
 
 ~IF toplevel_anonymous_class
 
-```java
+```java,editable
 void main() {
     System.out.println("Apple");
     System.out.println("Banana");

src/first_steps/comments.md

@@ -8,7 +8,7 @@ words.
 
 ~IF toplevel_anonymous_class
 
-```java, no_run
+```java
 void main() {
     // This prints hello world!
     System.out.println("Hello, World!");
@@ -17,7 +17,7 @@ void main() {
 
 ~ELSE
 
-```java, no_run
+```java
 public class Main {
     public static void main(String[] args) {
         // This prints hello world!

src/first_steps/formatting.md

@@ -5,10 +5,8 @@ You may have noticed that after each `{` all the code that comes after it is "in
 ~IF toplevel_anonymous_class
 
 ```java
-public class Main {
-    public static void main(String[] args) {
-        System.out.println("Hello, World!");
-    }
+void main() {
+    System.out.println("Hello, World!");
 }
 ```