Input and Output

lessons/en/chapter_10.yaml

@@ -1,10 +1,150 @@
-- title: Chapter 10 - The End
+- title: Chapter 10 - I/O
   content_markdown: >
-    It's been a joy to have you on the Tour of Rust. Ferris and the Tour of Rust
-    team sincerely hope you enjoy the journey ahead! If you 
+    In computing, `I/O` is an abbreviation for `Input/Output` operation.
+
+    The `input` is that the computer and tha algorithm receive and
+    the `output` represents the result generated based on the `input`.
+
+    Thing about `I/O` as a stream of information
+
+    A compute system without output is nearly useless.
+
+    It will always run the same code on the same data and, thus, produce the same result.
 
-    have felt comfortable this far, we strongly recommend diving deeper with
-    these resources:
+- title: Do it locally
+  content_markdown: >
+    In this chapter, the Playground will be just a code support for you :(.
+
+    Since most of the `I/O` programs are designed to compile on a local machine
+    (yours :) ), consider setting up a Rust environment on your personal computer and
+    familiarise yourself with the terminal.
+
+    Also, consider using a `IDE`, such as `VS Code` or `RustRover`
+    and familiarise yourself with the [terminal](https://www.youtube.com/watch?v=lZ7Kix9bjPI).
+
+- title: Standard Input (stdin)
+  content_markdown: >
+    `Standard Input` refers to the data provided by the user in order for the algorithm
+    to make something with it.
+
+
+    Thus, the `input` represents what a program is being given.
+    Mostly, in terms of `input`, you'll work with `String` and `files`.
+
+
+    The Rust library `std::io` has the necessary components to interact with `I/O`
+    channels, such as the keyboard or any other input source.
+  code: >-
+    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=use+std%3A%3Aio%3B%0A%0Afn+main%28%29+%7B%0A++++let+mut+input+%3D+String%3A%3Anew%28%29%3B%0A%0A++++%2F%2F+the+read+will+be+stopped+by+%60%5Cn%60+character%0A++++if+let+Ok%28_%29+%3D+io%3A%3Astdin%28%29.read_line%28%26mut+input%29+%7B%0A++++++++println%21%28%22Input+text+%3A+%7B%7D%22%2C+input%29%3B%0A++++%7D%0A%7D%0A
+
+- title: Standard Output (stdout)
+  content_markdown: >
+    Remember the first lesson? Can you notice something relevant to `I/O`?
+
+    Of course that `println!` is does an output operation,
+    in fact it directs (outputs) text to `stdout` (stdout)
+    and it will be displayed on the screen.
+
+    If you don't want to print a new line character `\n` for you, use `print!`
+  code: >-
+    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=use+std%3A%3Aio%3B%0A%0Afn+main%28%29+%7B%0A++++let+mut+input+%3D+String%3A%3Anew%28%29%3B%0A%0A++++%2F%2F+the+read+will+be+stopped+by+%60%5Cn%60+character%0A++++if+let+Ok%28_%29+%3D+io%3A%3Astdin%28%29.read_line%28%26mut+input%29+%7B%0A++++++++println%21%28%22Input+text+%3A+%7B%7D%22%2C+input%29%3B%0A++++%7D%0A%7D%0A
+
+- title: Standard Error (stdout)
+  content_markdown: >
+    In order to separate error reporting from common printing, you can use `eprint!` and
+    `eprintln!` macros that will display text in the standard error (`stderr`) channel,
+    instead of `stdout`. Use this macro with an informative message.
+
+    In UNIX-like systems, such as macOS or LINUX, you can separate the two types of
+    output by using redirections:
+    - `./main > output.txt`
+    - `./main >> output.txt`
+    - `./main 2> output.txt`
+    - `./main 2>> output.txt`
+
+
+    > The commands with `2` with copy only the errors generated by the program, and the ones without `2` will discards all error.
+
+    > THe command with `>>` will add text at the end of the file, while the operator `>` will override the file.
+  code: >-
+    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=use+std%3A%3Aio%3B%0A%0Afn+main%28%29+%7B%0A++++let+mut+input+%3D+String%3A%3Anew%28%29%3B%0A%0A++++%2F%2F+the+read+will+be+stopped+by+%60%5Cn%60+character%0A++++if+let+Ok%28_%29+%3D+io%3A%3Astdin%28%29.read_line%28%26mut+input%29+%7B%0A++++++++println%21%28%22Input+text+%3A+%7B%7D%22%2C+input%29%3B%0A++++%7D%0A%7D%0A
+
+- title: File Descriptors
+  content_markdown: >
+    Now that we know what are the basic `I/O` operations, we dive even deeper.
+
+    You've already seen before: `stdin` (standard input), `stdout` (standard output) and `stderr` (stand error).
+    For each of them it is associated a positive integer number, a unique identifier
+    for an `I/O` channel (example: file), known as a `file descriptor (fd)`.
 
-    * [The Official Rust Programming
-    Book](https://doc.rust-lang.org/stable/book/)
+    Therefore:
+    - `stdin`: 0
+    - `stdout`: 1
+    - `stderr`: 2
+    - files
+
+    [![file descriptors](https://cs-pub-ro.github.io/operating-systems/assets/images/file-descriptors-d19424f0a417ecd1c032f98a1969ad75.svg)
+
+
+    Working with files plays an important role in the `I/O` operations.
+
+    You've already learned to open a text file and read its content.
+
+    But how about writing data in it, as an `I/O` channel.
+  code: >-
+    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=use+std%3A%3Afs%3A%3A%7Bself%2C+File%7D%3B++++++%2F%2F+file+system%0Ause+std%3A%3Aio%3A%3A%7Bself%2C+Write%7D%3B+++++%2F%2F+input+output%0A%0Afn+main%28%29+-%3E+io%3A%3AResult%3C%28%29%3E+%7B%0A++++let+file_name+%3D+%22output.txt%22%3B%0A%0A++++%2F%2F+creates+the+file+if+it+doesn%27t+already+exists%0A++++let+mut+file+%3D+File%3A%3Acreate%28file_name%29%3F%3B%0A%0A++++let+text_to_write+%3D+%22Hello%2C+World%21%5Cn%5C%0A++++++++++++++++++++++++++++This+is+a+line+of+text.%5Cn%22%3B%0A++++file.write_all%28text_to_write.as_bytes%28%29%29%3F%3B%0A%0A++++let+absolute_path+%3D+fs%3A%3Acanonicalize%28file_name%29%3F%3B%0A++++println%21%28%22Text+has+been+written+to%3A+%7B%3A%3F%7D%22%2C+absolute_path%29%3B%0A%0A++++return+Ok%28%28%29%29%3B%0A%7D%0A
+
+- title: System Arguments
+  content_markdown: >
+    A Rust program is able to receive `input` from the in-line arguments.
+
+    In order to do so, open a [terminal](https://www.youtube.com/watch?v=lZ7Kix9bjPI), compile it and pass the arguments to the executable in the command promt.
+
+    These arguments might be relevant files, flags and so on.
+    The developer must document their purpose.
+
+    If you are using LINUX or macOS, bear in mind these commands:
+    ```bash
+    $ touch main.rs
+    $ rustc main.rs
+    $ ./main.rs 2 3 4 5 
+    ```
+
+    Otherwise, for Windows environment, on a PowerShell and paste them
+    ```PowerShell
+    > echo. > main.rs
+    > rustc main.rs
+    > .\main.exe 2 3 4 5
+    ```
+
+
+    > Notice that the first argument is the executable itself
+
+  code: >-
+    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=use+std%3A%3Aenv%3B+++++++%2F%2F+env+stands+for+environment%0A%0Afn+main%28%29+%7B%0A++++let+args%3A+Vec%3CString%3E+%3D+env%3A%3Aargs%28%29.collect%28%29%3B%0A++++println%21%28%22number+of+arguments+%3D+%7B%7D%22%2C+args.len%28%29%29%3B%0A++++println%21%28%22the+inline+arguments+are+%3A+%7B%3A%3F%7D%22%2C+args%29%3B%0A%7D%0A
+
+- title: Environment Variables
+  content_markdown: >
+    You've seen that the Rust standard library grants access to the system.
+
+    Using the `std::env` module, you can do in Rust some task that might require
+    a UNIX terminal, such as:
+    - command line arguments
+    - printing the current working directory
+    - current executable path
+    - working with environmental variables
+    - working with files and directories
+
+  code: >-
+    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=use+std%3A%3Aenv%3B+++%2F%2F+for+interacting+with+the+system%27s+environment%0A%0Afn+main%28%29+%7B%0A%0A++++if+let+Ok%28current_dir%29+%3D+env%3A%3Acurrent_dir%28%29+%7B%0A++++++++if+let+Some%28pwd%29+%3D+current_dir.to_str%28%29+%7B%0A++++++++++++println%21%28%22The+current+working+directory+%3D+%7B%7D%22%2C+pwd%29%3B%0A++++++++%7D%0A++++%7D%0A%0A++++%2F%2F+%24+echo+%24PWD++++++%23+environment+variable%0A++++%2F%2F+if+you+don%27t+want+to+see+Seme%28...%29%2C+you+have+to+pattern+match+on+Ok%28%29%0A++++println%21%28%22The+current+working+directory+%3D+%7B%3A%3F%7D%22%2C+env%3A%3Avar%28%22PWD%22%29.ok%28%29%29%3B%0A%0A++++%2F%2F+%24+echo+%24PWD++++++%23+environment+variable%0A++++if+let+Ok%28pwd%29+%3D+env%3A%3Avar%28%22PWD%22%29+%7B%0A++++++++println%21%28%22The+current+working+directory+%3D+%7B%7D%22%2C+pwd%29%3B%0A++++%7D%0A%0A++++%2F%2F+%24+echo+%24USER+++++%23+environment+variable%0A++++if+let+Ok%28user%29+%3D+env%3A%3Avar%28%22USER%22%29+%7B%0A++++++++println%21%28%22The+current+user+is%3A+%7B%7D%22%2C+user%29%3B%0A++++%7D%0A%0A%0A++++%2F%2F+%24+echo+%24IDK++++++%23+I+suppose+you+didn%27t+set+this+variable+%3A%29%0A++++if+let+Err%28err%29+%3D+env%3A%3Avar%28%22IDK%22%29+%7B%0A++++++++eprintln%21%28%22IDK+%3A+%7B%7D%22%2C+err%29%3B%0A++++++++env%3A%3Aset_var%28%22IDK%22%2C+%22%3D+I+don%27t+know%22%29%3B%0A++++++++println%21%28%22IDK+%3D+%7B%3A%3F%7D%22%2C+env%3A%3Avar%28%22IDK%22%29.ok%28%29%29%3B%0A++++++++env%3A%3Aremove_var%28%22IDK%22%29%3B%0A++++%7D%0A%7D%0A
+- title: Chapter 11 - Conclusion
+  content_markdown: >
+    Now that you know the basic of Input/Output operations, you used just two
+    Rust libraries along the way, and they are standard, btw: `std::env` and `std::fs`.
+
+    Now, you can build your own file managing system, Web App or even API.
+
+    Checkout these resources:
+    - [Environment Variables](https://youtu.be/npsMN-tZNVs)
+    - [Rust API](https://youtu.be/_ccDqRTx-JU)
+

lessons/en/chapter_11.yaml

@@ -0,0 +1,10 @@
+- title: Chapter 11 - The End
+  content_markdown: >
+    It's been a joy to have you on the Tour of Rust. Ferris and the Tour of Rust
+    team sincerely hope you enjoy the journey ahead! If you 
+
+    have felt comfortable this far, we strongly recommend diving deeper with
+    these resources:
+
+    * [The Official Rust Programming
+    Book](https://doc.rust-lang.org/stable/book/)

lessons/en/chapter_2.yaml

@@ -67,33 +67,49 @@
 
     and including an end number.
   code: >-
-    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=fn%20main()%20%7B%0A%20%20%20%20for%20x%20in%200..5%20%7B%0A%20%20%20%20%20%20%20%20println!(%22%7B%7D%22%2C%20x)%3B%0A%20%20%20%20%7D%0A%0A%20%20%20%20for%20x%20in%200..%3D5%20%7B%0A%20%20%20%20%20%20%20%20println!(%22%7B%7D%22%2C%20x)%3B%0A%20%20%20%20%7D%0A%7D%0A
+    https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&code=fn+main%28%29+%7B%0A%0A++++for+x+in+0..5+%7B%0A++++++++print%21%28%22%7B%7D+%22%2C+x%29%3B%0A++++%7D%0A++++println%21%28%29%3B%0A%0A++++for+x+in+0..%3D5+%7B%0A++++++++print%21%28%22%7B%7D+%22%2C+x%29%3B%0A++++%7D%0A++++println%21%28%29%3B%0A%0A++++let+nums+%3A+%5Bi32%3B+5%5D+%3D+%5B10%2C+-1%2C+9%2C+-80%2C+1%5D%3B%0A++++%0A++++print%21%28%22%7B%7D+%3A+%22%2C+stringify%21%28nums%29%29%3B%0A++++for+el+in+nums+%7B%0A++++++++print%21%28%22%7B%7D+%22%2C+el%29%3B%0A++++%7D%0A++++println%21%28%29%3B%0A%0A++++print%21%28%22%7B%7D+%3A+%22%2C+stringify%21%28nums%29%29%3B%0A++++for+idx+in+0+..+nums.len%28%29+%7B%0A++++++++print%21%28%22%7B%7D+%22%2C+nums%5Bidx%5D%29%3B%0A++++%7D%0A++++println%21%28%29%3B%0A%7D%0A
 - title: match
   content_markdown: >
-    Miss your switch statement? Rust has an incredibly useful keyword
+    Miss your switch statement?
+
+    Rust has an incredibly useful keyword for
+    matching all possible conditions of a value
+    and executing a code path if the match is true. 
+
+    Let's see how this works for numbers. We will have more to
+    say in future chapters on pattern matching more complex data. I promise you
+    it will be worth the wait.
+
+
+    `match` is exhaustive so all cases must be handled.
+
+    If the branches do not cover all the possible cases,
+    we'll use the underscore `_`, that will take place for the rest of them,
+
+    Matching combined with destructuring is by far one of the most common patterns you will see in all of Rust.
 
-    for matching all possible conditions of a value and executing a code path if
-    the
-
-    match is true. Let's see how this works for numbers. We will have more to
-    say
-
-    in future chapters on pattern matching more complex data. I promise you it
-    will
 
-    be worth the wait.
-
-
-    `match` is exhaustive so all cases
+    Matching combined with destructuring is by far one of the
+    most common patterns you will see in all of Rust.
+  code: >-
+    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=fn+main%28%29+%7B%0A++++let+x+%3D+42%3B%0A%0A++++match+x+%25+2+%3D%3D+0+%7B%0A++++++++true+%3D%3E+println%21%28%22%7B%7D+is+an+even+number%22%2C+x%29%2C%0A++++++++false+%3D%3E+println%21%28%22%7B%7D+is+an+odd+number%22%2C+x%29%2C%0A++++%7D%0A%0A++++match+x+%7B%0A++++++++0+%3D%3E+%7B%0A++++++++++++println%21%28%22found+zero%22%29%3B%0A++++++++%7D%0A++++++++%2F%2F+we+can+match+against+multiple+values%0A++++++++1+%7C+2+%3D%3E+%7B%0A++++++++++++println%21%28%22found+1+or+2%21%22%29%3B%0A++++++++%7D%0A++++++++%2F%2F+we+can+match+against+ranges%0A++++++++3..%3D9+%3D%3E+%7B%0A++++++++++++println%21%28%22found+a+number+3+to+9+inclusively%22%29%3B%0A++++++++%7D%0A++++++++%2F%2F+we+can+bind+the+matched+number+to+a+variable%0A++++++++matched_num+%40+10..%3D100+%3D%3E+%7B%0A++++++++++++println%21%28%22found+%7B%7D+number+between+10+to+100%21%22%2C+matched_num%29%3B%0A++++++++%7D%0A++++++++%2F%2F+do+nothing+if+x+equals+101%0A++++++++101+%3D%3E+%28%29%2C%0A++++++++%2F%2F+this+is+the+default+match+that+must+exist+if+not+all+cases+are+handled%0A++++++++_+%3D%3E+%7B%0A++++++++++++println%21%28%22found+something+else%21%22%29%3B%0A++++++++%7D%0A++++%7D%0A%7D%0A
+- title: matching multiple parameters
+  content_markdown: >
+    The `match` statements expects a tuple.
 
-    must be handled.
+    Notice that, unlike the `if` statement,
+    the code will compile just fine if you try
+    to place the evaluation elements in parenthesis `()`.
 
+    But why?...🤔
 
-    Matching combined with destructuring is by far one of the
+    Because the element is seen as a `tuple`
+    (a collection of elements that are able to have different types).
 
-    most common patterns you will see in all of Rust.
+    `tuples` are really powerful to use if you want
+    to match multiple elements together.
   code: >-
-    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=fn%20main()%20%7B%0A%20%20%20%20let%20x%20%3D%2042%3B%0A%0A%20%20%20%20match%20x%20%7B%0A%20%20%20%20%20%20%20%200%20%3D%3E%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20println!(%22found%20zero%22)%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%2F%2F%20we%20can%20match%20against%20multiple%20values%0A%20%20%20%20%20%20%20%201%20%7C%202%20%3D%3E%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20println!(%22found%201%20or%202!%22)%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%2F%2F%20we%20can%20match%20against%20ranges%0A%20%20%20%20%20%20%20%203..%3D9%20%3D%3E%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20println!(%22found%20a%20number%203%20to%209%20inclusively%22)%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%2F%2F%20we%20can%20bind%20the%20matched%20number%20to%20a%20variable%0A%20%20%20%20%20%20%20%20matched_num%20%40%2010..%3D100%20%3D%3E%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20println!(%22found%20%7B%7D%20number%20between%2010%20to%20100!%22%2C%20matched_num)%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%2F%2F%20this%20is%20the%20default%20match%20that%20must%20exist%20if%20not%20all%20cases%20are%20handled%0A%20%20%20%20%20%20%20%20_%20%3D%3E%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20println!(%22found%20something%20else!%22)%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%7D%0A
+    https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=fn+main%28%29+%7B%0A++++let+x+%3D+42%3B%0A++++let+y+%3D+-101%3B%0A+%0A++++%2F%2F+the+program+compiles%0A++++%2F%2F+but+the+parantheses+are+unnecessary+for+just+an+element%0A++++match+%28x+%25+2+%3D%3D+0%29+%7B%0A++++++++%28true%29+%3D%3E+println%21%28%22%7B%7D+is+an+even+number%22%2C+x%29%2C%0A++++++++false+%3D%3E+println%21%28%22%7B%7D+is+an+odd+number%22%2C+x%29%2C%0A++++%7D%0A%0A+%0A++++match+%28x+%3E%3D+0%2C+y+%3E%3D+0%29+%7B%0A++++++++%28true%2C+true%29+%3D%3E+println%21%28%22Both+numbers+%7B%7D+%7B%7D+are+positive%22%2C+x%2C+y%29%2C%0A++++++++%28true%2C+false%29+%3D%3E+println%21%28%22Only+%7B%7D+is+a+positive+number%22%2C+x%29%2C%0A++++++++%28false%2C+true%29+%3D%3E+println%21%28%22Only+%7B%7D+is+a+negative+number%22%2C+y%29%2C%0A++++++++%28false%2C+false%29+%3D%3E+println%21%28%22Both+numbers+%7B%7D+%7B%7D+are+negative%22%2C+x+%2Cy%29%2C%0A++++%7D%0A%7D%0A
 - title: Returning Values From loop
   content_markdown: |
     `loop` can break to return a value.