2nd edition - support rust 2018

Author: donaldpipowitch

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "bungcip.better-toml",
+    "esbenp.prettier-vscode",
+    "rust-lang.rust"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "editor.formatOnSave": true,
+  "prettier.arrowParens": "always",
+  "prettier.singleQuote": true
+}

README.md

@@ -2,11 +2,15 @@
 
 > An introduction to the Rust programming language for Node developers.
 
-Hi there, [I'm a JavaScript developer](https://github.com/donaldpipowitch) who wants to learn Rust and as a part of this process I'll write here about my learnings. So what is Rust actually and **why should you learn it**? Rust is a systems programming language like C or C++, but with influences from functional programming languages and even scripting languages like JavaScript. It _feels_ very modern - which is no surprise, because it is a relatively young language. [It went 1.0 in 2015!](http://blog.rust-lang.org/2015/05/15/Rust-1.0.html) That doesn't only mean it is _fun to write_, because it has less clutter to carry around, it is also _fun to use_, because it has a modern toolchain with a great package manager. Rust's most unique feature is probably the compile-time safety check: it catches errors like segfaults without introducing a garbage collector. Or to phrase it differently: maximum safety with maximum performance.
+> 💡 **2nd edition.** I initially wrote this tutorial in the summer of 2016. Rust 1.0 was roughly a year old back than. This tutorial stayed quite popular over time even though I haven't added new chapters. As years passed by the Rust (and Node) ecosystem evolved further and this tutorial wasn't up-to-date with all changes. With the recent release of [_"Rust 2018"_](https://blog.rust-lang.org/2018/12/06/Rust-1.31-and-rust-2018.html) (which I'll explain later in more depth) I took the opportunity to update this tutorial as well. Enjoy the read! 🎉
 
-Probably even more important than its features is the ecosystem and the community behind the language. Rust really shines here - especially for people who love the web. It is **backed by Mozilla** and the **biggest real world project** written in Rust is probably [servo](https://github.com/servo/servo), a modern browser engine. servo is very modular - e.g. you can require its [HTML parser as a standalone module](https://github.com/servo/html5ever). Can you do that with any other browser engine? As far as I know... _no_. [Chances are pretty high](http://blog.rust-lang.org/2016/05/13/rustup.html) that Rust will become a good host platform for [wasm](https://github.com/webassembly) - the future binary format for the web.
+Hi there, I'm Donald. [I'm a JavaScript developer](https://github.com/donaldpipowitch) who wants to learn Rust and as a part of this process I'll write here about my learnings. But what is Rust and **why do I want learn it**? Rust is a systems programming language like C or C++, but with influences from functional programming languages and even scripting languages like JavaScript. It _feels_ very modern - which is no surprise, because it is a relatively young language. [It went 1.0 in 2015!](http://blog.rust-lang.org/2015/05/15/Rust-1.0.html) That doesn't only mean it is _fun to write_, because it has less clutter to carry around, it is also _fun to use_, because it has a modern toolchain with a great package manager. Rust's most unique feature is probably the compile-time safety check: it catches errors like segfaults without introducing a garbage collector. Or to phrase it differently: maximum safety with maximum performance.
 
-Before we dive into our setup we want to look at least once into a real Rust file:
+Probably even more important than its features is the ecosystem and the community behind the language. Rust really shines here - especially for people who love the web. The language was (and still is) heavily influenced by developers from Mozilla. They have written [`servo`](https://github.com/servo/servo), a modern browser engine, in Rust and [parts of Firefox are now running Rust code](https://hacks.mozilla.org/2017/11/entering-the-quantum-era-how-firefox-got-fast-again-and-where-its-going-to-get-faster/). [Rust is also great for authoring WebAssembly code](https://www.rust-lang.org/what/wasm) (short: _Wasm_), a [binary format for the web](https://webassembly.org/), which is [supported in Firefox, Edge, Chrome and Safari](https://caniuse.com/#feat=wasm).
+
+To summarize: Rust is a young modern language with a great tooling and ecosystem, good safety and performance promises and which can be used for a lot of different projects - from low level tasks to command line tools and even web projects.
+
+Before we dive into our tutorial we want to look at least once into a real Rust file:
 
 ```rust
 fn main() {
@@ -16,28 +20,28 @@ fn main() {
 
 The JavaScript equivalent _could roughly_ look like this:
 
-```javascript
+```js
 function main() {
   console.log('Hello World!');
 }
 ```
 
 Nothing too scary, right? The `!` behind `println` could be a bit confusing, but don't mind it for now. Just think of it as a special function.
 
-How do we move on from here? First I'll guide you how my current setup looks like to use Node and Rust. After that I'll create several kitchen sink like examples - first with Node and then with Rust. I'll try to explain them as best as I can, but _don't_ expect in-depth explanations in every case. Don't forget that I'm trying to learn Rust - _just like you_. Probably you need to explain _me_ some things, too! Oh, and before I forget it: my Node examples will be written in [TypeScript](https://www.typescriptlang.org/) actually! I think it makes some examples easier to compare to Rust and if you experience sweet type safety from Rust you want a little bit of that in your Node projects anyway ;)
+How do we move on from here? First I'll guide you how my current setup looks like to use Node and Rust. Many people seemed to like that I introduce some convenient tooling and IDE configurations _before_ actually speaking about Rust itself. But you can skip this chapter, if you want. After the setup step I'll create several kitchen sink like examples - first with Node and then with Rust. I'll try to explain them as best as I can, but _don't_ expect in-depth explanations in every case. Don't forget that I'm trying to learn Rust - _just like you_. Probably you need to explain _me_ some things, too! And before I forget it: my Node examples will be written in [TypeScript](https://www.typescriptlang.org/)! Writing them in TypeScript will make it a little bit easier to compare some examples to Rust.
 
-I try to add an example every two weeks.
+One word about the structure of this tutorial before we start. Every chapter has its own directory. If a chapter has sub-chapters they also have sub-directories. And if a (subd-)chapter contains code examples, you'll find a `node` and a `rust` directory which contain all the code of this (sub-)chapter. (One example: The chapter [_"Package Manager"_](package-manager/README.md) can be found inside [`package-manager/`](package-manager). It has the sub-chapter [_"Publishing"_](package-manager/README.md#publishing) and the corresponding code examples can be found in [`package-manager/publishing/node/`](package-manager/publishing/node) and [`package-manager/publishing/rust/`](package-manager/publishing/rust).)
 
 # Table of contents
 
-0. [Setup](setup/README.md)
-0. [Hello World](hello-world/README.md)
-0. [Package Manager](package-manager/README.md)
-0. [Read files](read-files/README.md)
-0. [Write files](write-files/README.md)
-0. [HTTP requests](http-requests/README.md)
-0. [Parse JSON](parse-json/README.md)
+1. [Setup](setup/README.md)
+2. [Hello World](hello-world/README.md)
+3. [Package Manager](package-manager/README.md)
+4. [Read files](read-files/README.md)
+5. [Write files](write-files/README.md)
+6. [HTTP requests](http-requests/README.md)
+7. [Parse JSON](parse-json/README.md)
 
-Thank you for reading this article. ♥
+Thank you for reading this tutorial. ♥
 
 I highly appreciate pull requests for grammar and spelling fixes as I'm not a native speaker. Thank you!

hello-world/README.md

@@ -2,9 +2,9 @@
 
 Ah, yes! A classic _"Hello world!"_ example. This one will be really quick, but I'll show you an important difference between Node and Rust.
 
-Create a `hello-world.js` containing nothing more than this line:
+Create a [`hello-world.js`](hello-world/node/hello-world.js) containing nothing more than this line:
 
-```javascript
+```js
 console.log('Hello world!');
 ```
 
@@ -17,31 +17,31 @@ Hello world!
 
 _Yeah!_ You'll see `Hello world!` in your console.
 
-Now we'll do the same for Rust. Create a `hello_world.rs` with the followind content:
+Now we'll do the same for Rust. Create a [`hello_world.rs`](hello-world/rust/hello_world.rs) with the following content:
 
 ```rust
 fn main() {
     println!("Hello world!");
 }
 ```
 
-Rust actually needs a special entry point to execute code. This is our `main` function and as you can see a function in Rust is declared like in JavaScript, just with the `fn` keyword instead of `function`. It is important to call the function `main` or the Rust compiler will throw an error. In Rust we typically use 4 spaces to indent code inside a function. In JavaScript most projects I know (and [the Standard Style](https://github.com/feross/standard)) use 2 spaces. Rust also recommends `snake_case` naming style for directories and files while I think `kebab-case` is most common in JavaScript projects. `println` isn't a simple function call, but a macro - which is indicated by the `!`. For now think of a macro as some code which is transformed into other code at compile time. Last but not least you _need_ to wrap your string inside `"`, not `'`. In JavaScript there is no difference between `"` and `'` to create strings and [many](https://github.com/feross/standard) prefer to use `'`. In Rust a `"` creates a _string literal_ while `'` creates a _character literal_ which means it only accepts a single character. You could write `println!("H");` or `println!('H');` and both would compile, but `println!('Hello World!');` throws an error.
+Rust actually needs a special entry point to execute code. This is our `main` function and as you can see a function in Rust is declared like in JavaScript, but with the `fn` keyword instead of `function`. It is important to call the function `main` or the Rust compiler will throw an error. In Rust we typically use 4 spaces to indent code inside a function, while 2 spaces are more common for JavaScript projects. (But thankfully this is covered by prettier anyway and it could be covered by `rustfmt` when [my feature request will be solved](https://github.com/rust-lang/rls/issues/1198).) Rust also recommends `snake_case` naming style for directories and files while I think `kebab-case` is most common in JavaScript projects. `println` isn't a simple function call, but a macro - which is indicated by the `!`. For now think of a macro as some code which is transformed into other code at compile time. Last but not least you _need_ to wrap your string inside `"`, not `'`. In JavaScript there is no difference between `"` and `'` to create strings (and [many](https://github.com/feross/standard) prefer to use `'`, even though it's not prettiers default). In Rust a `"` creates a _string literal_ while `'` creates a _character literal_ which means it only accepts a _single character_. You could write `println!("H");` or `println!('H');` and both would compile, but `println!('Hello World!');` throws an error.
 
 Now compile our code with the following command:
 
 ```bash
 $ rustc hello-word.rs
 ```
 
-You'll see... nothing on your console. Instead a new file called `hello-world` was created next to `hello-world.rs`. This is our compiled code. You can run it like this:
+You'll see... nothing on your console. Instead a new file called `hello-world` was created next to `hello-world.rs`. This file contains our compiled code. You can run it like this:
 
 ```bash
 $ ./hello-world
 Hello world!
 ```
 
-Now you'll see `Hello world!` in your console. This shows a fundamental difference between JavaScript/Node and Rust. Rust needs to be compiled before our program can be executed. This extra step is not needed for JavaScript which makes the development cycle with JavaScript sometimes faster. However the compilation step catches a ton of bugs _before_ even executing your program. This can be _so_ useful that you probably often want to introduce something similar to JavaScript - like TypeScript. There is another big benefit: we can easily share our compiled `hello-world` program with other developers _without_ the need for them to have Rust installed. This is not possible with Node scripts. Everyone who wants to run our `hello-world.js` needs to have Node installed.
+Now you'll see `Hello world!` in your console. This shows a fundamental difference between JavaScript/Node and Rust. Rust needs to be compiled before our program can be executed. This extra step is not needed for JavaScript which makes the development cycle with JavaScript sometimes faster. However the compilation step catches a ton of bugs _before_ even executing your program. This can be _so_ useful that you probably want to introduce a similar sanity check to JavaScript - for example by using TypeScript. There is another big benefit: we can easily share our compiled `hello-world` program with other developers _without_ the need for them to have Rust installed. This is not possible with Node scripts. Everyone who wants to run our `hello-world.js` needs to have Node installed and in a version which is supported by our script.
 
-______
+---
 
-← [prev](../setup/README.md) | [next](../package-manager/README.md) →
+← [prev _"Setup"_](../setup/README.md) | [next _"Package Manager"_](../package-manager/README.md) →

hello-world/rust/hello_world

@@ -8,17 +8,19 @@ Because GitHubs API is served over `https` we'll use Node's `https` module. We c
 
 So this is our basic example:
 
-```typescript
+```ts
 import { get } from 'https';
 
 const host = 'api.github.com';
 const path = '/users/donaldpipowitch';
 
 get({ host, path }, (res) => {
   let buf = '';
-  res.on('data', (chunk) => buf = buf + chunk);
+  res.on('data', (chunk) => (buf = buf + chunk));
   res.on('end', () => console.log(`Response: ${buf}`));
-}).on('error', (err) => { throw `Couldn't send request.` });
+}).on('error', (err) => {
+  throw `Couldn't send request.`;
+});
 ```
 
 We import the `get` function from `https`. We declare a `host` and `path` (no need to set the protocol, when we already use the `https` module). After that we call `get` and pass an options object (containing our `host` and `path`) and callback whic accepts a response object (`res`) as the _first_ parameter. Yes, `get` doesn't follow the usual callback style pattern of Node where the first param is an error and the second param is a result. It is more low level than that. Instead we have an request object (the return value of `get`) and an response object (`res`) which are both event emitters. We listen for `error` events on the request object and in case of an error we just `throw` `Couldn't send request.` to exit our program.
@@ -66,7 +68,7 @@ get({ host, path }, (res) => {
 +    }
 +  });
 }).on('error', (err) => { throw `Couldn't send request.` });
-````
+```
 
 Test the program again:
 
@@ -240,7 +242,7 @@ After that we read our result into a buffer (`buf`) and print the response body.
 If you run our program now you see the same error as in our first Node example:
 
 ```
-$ cargo run -q
+$ cargo -q run
 Response: Request forbidden by administrative rules. Please make sure your request has a User-Agent header (http://developer.github.com/v3/#user-agent-required). Check https://developer.github.com for other possible causes.
 ```
 
@@ -278,7 +280,7 @@ Note that we use an `if` statement in Rust for the first time. Unlike JavaScript
 Test the program again:
 
 ```
-$ cargo run -q
+$ cargo -q run
 Response: Request forbidden by administrative rules. Please make sure your request has a User-Agent header (http://developer.github.com/v3/#user-agent-required). Check https://developer.github.com for other possible causes.
 
 thread '<main>' panicked at 'Got client error: 403 Forbidden', src/main.rs:50
@@ -332,12 +334,12 @@ We import `Headers` and `UserAgent` from `hyper::header`. We create a new instan
 The last thing we need to do is passing our `headers` to our actually request with the `headers` method, just before we call `send`. Done!
 
 ```
-$ cargo run -q
+$ cargo -q run
 Response: {"login":"donaldpipowitch","id":1152805, ...
 ```
 
 The Node and the Rust example both show the same result now. Nice. In the next example I'll show you how to actually handle a JSON response.
 
-______
+---
 
-← [prev](../write-files/README.md) | [next](../parse-json/README.md) →
+← [prev _"Write files"_](../write-files/README.md) | [next _"Parse JSON"_](../parse-json/README.md) →

http-requests/README.md

@@ -2,6 +2,7 @@
 name = "http-requests"
 version = "1.0.0"
 publish = false
+edition = "2018"
 
 [dependencies]
 hyper = "0.9.0"