- Please star and contribute to our Github π + Please star our Github and use our apps & libsπ
-
-
+
-
-
+
-
-
+
+
+
+
-
+
+
+
diff --git a/_posts/2019-10-31-fish-scripting-manual.md b/_posts/2019-10-31-fish-scripting-manual.md
index 3ae98463..31fc0f8c 100644
--- a/_posts/2019-10-31-fish-scripting-manual.md
+++ b/_posts/2019-10-31-fish-scripting-manual.md
@@ -48,7 +48,7 @@ categories:
-Learn how to write fish shell scripts by example.
+{%- include featured.html -%}
## Shebang line at the top of your scripts
@@ -827,3 +827,5 @@ function timed -d Pass the program or function that you want to execute as an ar
echo "β² Total runtime: $RUNTIME min β²"
end
```
+
+{%- include featured.html -%}
diff --git a/_posts/2022-02-24-rust-non-binary-tree.md b/_posts/2022-02-24-rust-non-binary-tree.md
index e8c0c873..ef19d6fd 100644
--- a/_posts/2022-02-24-rust-non-binary-tree.md
+++ b/_posts/2022-02-24-rust-non-binary-tree.md
@@ -54,10 +54,9 @@ will be allow us to make the tree thread safe and parallel friendly (we will nam
> [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils) crate.
> π You can take a look the source code of this thread safe non-binary tree data structure named
-> `Arena` in its github [repo](https://github.com/r3bl-org/r3bl-rs-utils).
+> `Arena` in its github [repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/utils).
-> π Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if
-> you like it π.
+{%- include featured.html -%}
## Naive approach using weak and strong references
@@ -661,7 +660,6 @@ There are functions that make it easy to unwrap things in Rust that are wrapped
> [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils) crate.
> π You can take a look the source code of this thread safe non-binary tree data structure named
-> `Arena` in its github [repo](https://github.com/r3bl-org/r3bl-rs-utils).
+> `Arena` in its github [repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/utils).
-> π Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if
-> you like it π.
+{%- include featured.html -%}
diff --git a/_posts/2022-03-02-rust-grep-cli-app.md b/_posts/2022-03-02-rust-grep-cli-app.md
index 7c5b5f7e..f6e963a3 100644
--- a/_posts/2022-03-02-rust-grep-cli-app.md
+++ b/_posts/2022-03-02-rust-grep-cli-app.md
@@ -49,6 +49,8 @@ arguments, stdin, stdout, and piping.
> object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf)
> by Will Crichton demonstrating Typed Design Patterns with Rust.
+{%- include featured.html -%}
+
## Building the main function
The first thing we need to do is build the main function. This is where we will be routing
@@ -263,6 +265,4 @@ Here are a list of crates that are used in this app.
We will explore more complex TUIs built w/ Rust in the future.
-> π Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on
-> github if you like it π. If you would like to contribute to it, please click
-> [here](https://github.com/r3bl-org/r3bl-open-core/contribute).
+{%- include featured.html -%}
diff --git a/_posts/2022-03-12-rust-redux.md b/_posts/2022-03-12-rust-redux.md
index e3f84d50..f8e4cf36 100644
--- a/_posts/2022-03-12-rust-redux.md
+++ b/_posts/2022-03-12-rust-redux.md
@@ -50,12 +50,7 @@ tasks. But the reducer functions will be run in sequence (not in separate Tokio
> π The source code for the finished Redux library can be found
> [here](https://github.com/r3bl-org/r3bl-rs-utils).
-> π¦ You can use this Redux library today by adding
-> [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils/) crate as a dependency in your
-> `Cargo.toml`.
->
-> π Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if
-> you like it π.
+{%- include featured.html -%}
This article is getting us ready to building more complex TUI apps next using crates like `termion`
and `tui`.
@@ -638,9 +633,4 @@ Tokio tasks.
> information on this library in it's
> [`README`](https://github.com/r3bl-org/r3bl-rs-utils/blob/main/README.md#redux) file.
-> π¦ You can use this Redux library today by adding
-> [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils/) crate as a dependency in your
-> `Cargo.toml`.
->
-> π Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if
-> you like it π.
+{%- include featured.html -%}
diff --git a/_posts/2022-03-12-rust-tokio.md b/_posts/2022-03-12-rust-tokio.md
index 6391f757..d9ba5de2 100644
--- a/_posts/2022-03-12-rust-tokio.md
+++ b/_posts/2022-03-12-rust-tokio.md
@@ -49,6 +49,8 @@ more complex TUI apps next using crates like `termion` and `tui`.
> object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf)
> by Will Crichton demonstrating Typed Design Patterns with Rust.
+{%- include featured.html -%}
+
## Concurrency and async/await, vs parallelism
Concurrency is being able to break up your program or function into smaller tasks that can be
@@ -691,9 +693,4 @@ Tokio, along w/ the tutorials that are provided on the [Tokio website](https://t
We will take this and build upon it further to create a full Redux library in Rust using Tokio
[here](https://developerlife.com/2022/03/12/rust-redux/).
-> π¦ For a real implementation of this middleware and Redux library, check out the
-> [`r3bl_rs_utils`](https://crates.io/crates/r3bl_rs_utils/) crate. The README has excellent
-> documentation on async traits, parallel and concurrent execution, and Tokio.
->
-> π Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if
-> you like it π.
+{%- include featured.html -%}
diff --git a/_posts/2022-03-30-rust-proc-macro.md b/_posts/2022-03-30-rust-proc-macro.md
index 054e1bd1..269aa578 100644
--- a/_posts/2022-03-30-rust-proc-macro.md
+++ b/_posts/2022-03-30-rust-proc-macro.md
@@ -16,10 +16,12 @@ categories:
-
-
+
- [What are procedural macros](#what-are-procedural-macros)
+ - [Declarative macros have limitations](#declarative-macros-have-limitations)
+ - [Summary of proc vs decl macros](#summary-of-proc-vs-decl-macros)
+ - [Source code examples](#source-code-examples)
- [How to add a proc macro lib crate to your existing project](#how-to-add-a-proc-macro-lib-crate-to-your-existing-project)
- [Add an internal or core crate](#add-an-internal-or-core-crate)
- [What does a syn AST look like?](#what-does-a-syn-ast-look-like)
@@ -39,17 +41,20 @@ categories:
- [Better implementation that handles generics](#better-implementation-that-handles-generics)
- [Using quote!](#using-quote)
- [Eg 4 - Derive macro that generates a builder](#eg-4---derive-macro-that-generates-a-builder)
+ - [Stub out the implementation](#stub-out-the-implementation)
+ - [Testing the macro](#testing-the-macro)
+ - [Implementation details](#implementation-details)
- [Eg 5 - Attribute macro that adds logging to a function](#eg-5---attribute-macro-that-adds-logging-to-a-function)
- [Create entry in lib.rs](#create-entry-in-librs)
- [How to parse item?](#how-to-parse-item)
- [How to parse args containing attributes for variant 1?](#how-to-parse-args-containing-attributes-for-variant-1)
- [How to parse args containing set of identifiers for variant 2?](#how-to-parse-args-containing-set-of-identifiers-for-variant-2)
- [Learning resources](#learning-resources)
-- [Wrapping up](#wrapping-up)
-
+
## What are procedural macros
+
**Procedural macros** are a way for you to extend the Rust compiler and provide plugins that you can
use to extend the language. They are really powerful and require some more work to setup in an
@@ -64,16 +69,20 @@ declared in the `lib.rs` file). Here are the key benefits of procedural macros:
[DSL (domain specific language)](https://developerlife.com/2020/04/04/kotlin-dsl-intro/) like in
Kotlin and babel and JavaScript.
-> π‘ **Declarative macros** have many limitations (eg: they can't work with generics) but are easier
-> to use. If you have simple use cases they work great, since they are so easy to write. Here are
-> some resources to help you w/ learning declarative macros.
->
-> 1. [Declarative macros in `r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules)
-> 2. [Declarative macros included in this article's repo (but not covered in this article)](https://github.com/nazmulidris/rust_scratch/blob/main/macros/tests/decl/main.rs)
-> 3. [Little book of Rust macros](https://veykril.github.io/tlborm/introduction.html)
-> 4. [Great YT video on declarative macros](https://youtu.be/q6paRBbLgNw)
+### Declarative macros have limitations
+
+
+For example they can't work with generics. They are easier to write than procedural
+macros. If you have simple use cases they work great, since they are so easy to write.
+Here are some resources to help you w/ learning declarative macros.
+
+1. [Declarative macros in `r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules)
+2. [Declarative macros included in this article's repo (but not covered in this article)](https://github.com/nazmulidris/rust_scratch/blob/main/macros/tests/decl/main.rs)
+3. [Little book of Rust macros](https://veykril.github.io/tlborm/introduction.html)
+4. [Great YT video on declarative macros](https://youtu.be/q6paRBbLgNw)
-Here's a summary:
+### Summary of proc vs decl macros
+
| Macro type | Capabilities & limitations |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
@@ -82,25 +91,24 @@ Here's a summary:
| Procedural - derive | Can't touch token stream of annotated `struct` or `enum`, only add new token stream below; can declare helper attributes |
| Procedural - attribute | Like function-like, replaces token stream of annotated item (not just `struct` or `enum`) |
-> π **Source code examples**
->
-> 1. You can find "real world" examples of both declarative and procedural macros in the
-> `r3bl_rs_utils` [crate](https://crates.io/crates/r3bl_rs_utils).
->
-> - [proc macros](https://github.com/r3bl-org/r3bl-open-core/tree/main/macro)
-> - [decl macros](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules)
->
-> 2. You can find all the pedagogical examples of macros shown in this article in this
-> [repo](https://github.com/nazmulidris/rust_scratch/blob/main/macros/)
->
-> π Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if
-> you like it π.
+### Source code examples
+
+
+1. You can find "real world" examples of both declarative and procedural macros in the
+ `r3bl-open-core` [repo](https://github.com/r3bl-org/r3bl-open-core).
+ - [proc macros](https://github.com/r3bl-org/r3bl-open-core/tree/main/macro)
+ - [decl macros](https://github.com/r3bl-org/r3bl-open-core/search?q=macro_rules)
+2. You can find all the pedagogical examples of macros shown in this article in this
+ [repo](https://github.com/nazmulidris/rust_scratch/blob/main/macros/).
+
+{%- include featured.html -%}
> For more information on general Rust type system design (functional approach rather than
> object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf)
> by Will Crichton demonstrating Typed Design Patterns with Rust.
## How to add a proc macro lib crate to your existing project
+
Rust has two kinds of macros: declarative and procedural. Declarative macros are made using
`macro_rules!` inline in your code w/out creating a new lib crate. This article is about procedural
@@ -185,6 +193,7 @@ r3bl_rs_utils = "*"
> and then runs the test you give that script as an argument.
### Add an internal or core crate
+
There are situations where you will need to share code between your public crate and your procedural
macro crate. In this case you can add an internal or core crate to your project. The shared files
@@ -214,6 +223,7 @@ and run `cargo publish` on each and every dependent crate and they will be their
crate on crates.io.
## What does a syn AST look like?
+
Before writing macros, let's talk about how we need to think about things:
@@ -299,6 +309,7 @@ the string `"fn foo() -> u32 { 42 }"` using
> [dump-syntax](https://github.com/dtolnay/syn/blob/master/examples/dump-syntax/src/main.rs).
## How to write a proc macro of any kind
+
There are 3 kinds of proc macros. Once you've created a new library crate for them inside your
project, you write macros like the ones shown below.
@@ -342,6 +353,7 @@ pub fn log_entry_and_exit(args: TokenStream, input: TokenStream) -> TokenStream
```
### Strategy
+
The rough idea is that we will have to parse "things" into this `proc_macro2::TokenStream` in order
to manipulate them. They can be parsed into this AST from:
@@ -364,6 +376,7 @@ In order to do this parsing you have to use the
an `ItemFn` AST and then you can work w/ the fields provided by `ItemFn` after that.
### Examples
+
So here are some examples of what this looks like.
@@ -398,6 +411,7 @@ So here are some examples of what this looks like.
implement which allows you greater control over the parsing process.
### Writing your own Parse trait impl in different ways
+
This might not be intuitive, but you can parse the **same** `TokenStream` using various different
parsers. You can parse a `TokenStream` as a `Type` or `Ident` or whatever else depending on what you
@@ -490,6 +504,7 @@ impl Parse for ManagerOfThingInfo {
> team is also quite helpful.
## Eg 1 - Function-like macro that dumps the AST
+
Let's start our procedural macro journey w/ something very simple. It's a macro that doesn't really
emit any token stream. It just prints out the AST of the input as debug. So we won't be using
@@ -601,6 +616,7 @@ fn test_proc_macro() {
> parse a custom syntax.
## Eg 2 - Function-like macro that parses custom syntax
+
There are times when you need to create your own syntax or domain specific language. Examples of
this are JSX for React. Or DAO generators for a database. In these cases, it's not just about
@@ -630,6 +646,7 @@ procedural macro will do the rest.
> ideas on custom syntax parsing and creating custom error messages for the compiler.
### Desired syntax and behavior
+
Let's say that we want to parse a custom syntax like the following, which basically is a declaration
of how a manager for the struct `HashMap
+
+1. TUI library crate: Clone [this TUI library
+ repo](https://github.com/r3bl-org/r3bl-open-core/) for the [`r3bl_tui`
+ crate](https://crates.io/crates/r3bl_tui) to your local or remote machine. You can run
+ the examples in the
+ [README](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui#examples-to-get-you-started).
+2. TUI apps crate: Clone [this TUI apps
+ repo](https://github.com/r3bl-org/r3bl-open-core) for the [`r3bl-cmdr`
+ crate](https://crates.io/crates/r3bl-cmdr) to your local or remote machine. Run `cargo
+ run` (in `r3bl-cmdr` folder) to see it doing its thing. Works great over
+ [SSH](https://en.wikipedia.org/wiki/Secure_Shell) too! Or you can just run `cargo
+ install r3bl-cmdr`. And then run `edi` or `giti`.
+
+The TUI library allows developers to build "rich" text user interface apps in Rust, which
+are fully async, and loosely leverages architectural ideas from CSS, React, web app
+development paradigm, and Elm. Once we built the library, we wanted to make it easier for
+developer to declaratively create styling and even layouts, rather than having to do it
+imperatively.
> π In frontend web development, we take it for granted that we can describe things
> [declaratively rather than imperatively](https://www.educative.io/blog/declarative-vs-imperative-programming).
@@ -678,11 +686,4 @@ In the future we will expand this DSL to include more features like generating t
declaratively. And then move on to creating JSX like syntax in Rust for layout stuff in the `tui`
module as well. More articles to follow based on this work.
-> π For more examples of procedural macros, check out the
-> [`r3bl_rs_utils_macro`](https://github.com/r3bl-org/r3bl-open-core/tree/main/macro/)
-> repo.
->
-> π‘ This is part of the [`r3bl_rs_utils` crate](https://crates.io/crates/r3bl_rs_utils).
->
-> π Please star the [`r3bl-open-core` repo](https://github.com/r3bl-org/r3bl-open-core) on github if
-> you like it π.
+{%- include featured.html -%}
diff --git a/_posts/2022-11-21-algo-ts-1.md b/_posts/2022-11-21-algo-ts-1.md
index fede5b8a..39010144 100644
--- a/_posts/2022-11-21-algo-ts-1.md
+++ b/_posts/2022-11-21-algo-ts-1.md
@@ -47,6 +47,8 @@ This tutorial has 2 examples in it:
1. [String tokenizer](#exercise-1-string-tokenizer)
2. [Rate limiter](#exercise-2-in-memory-rate-limiter)
+{%- include featured.html -%}
+
### How to run this project
You can get the code for this and all the other tutorials in this collection from
@@ -114,7 +116,7 @@ string.
- The meaning of `action` string command: For example `action` can look like this:
`"../anotherFolder"`. This means we want to go up one folder (..) and then go into folder
- called anotherFolder.
+ called anotherFolder.
In order for us to understand what this `action` string means, we need to break it down into
smaller strings and store those smaller strings in an array as well.
- For example, `"../anotherFolder"` would be turned into an array of `["..", "anotherFolder"]`.
@@ -251,3 +253,5 @@ period.
3. In the outer function we check if the request was successful or not. It the request was
successful, we push the request timestamp to `successfulRequests` array and return "accept". If
the request was not successful, we return "deny".
+
+{%- include featured.html -%}
diff --git a/_posts/2022-12-11-algo-ts-2.md b/_posts/2022-12-11-algo-ts-2.md
index 43ea0d2d..87d7508d 100644
--- a/_posts/2022-12-11-algo-ts-2.md
+++ b/_posts/2022-12-11-algo-ts-2.md
@@ -44,6 +44,8 @@ created using TypeScript. Information is depicted visually using diagrams and co
article may be useful if you are trying to get more fluency in TypeScript or need a refresher to do
interview prep for software engineering roles.
+{%- include featured.html -%}
+
## Pretty print and traverse an HTML tree
@@ -269,3 +271,5 @@ All DFS methods use stack data structure. In JavaScript stack is an array where
after another and then remove them from the end of the array. It's called last-in-first-out (LIFO).
You could think of it as a stack of papers. The last paper you put on the stack is the first paper
you take off the stack.
+
+{%- include featured.html -%}
diff --git a/_posts/2023-02-20-guide-to-nom-parsing.md b/_posts/2023-02-20-guide-to-nom-parsing.md
index eeb597dc..f6b7f4e9 100644
--- a/_posts/2023-02-20-guide-to-nom-parsing.md
+++ b/_posts/2023-02-20-guide-to-nom-parsing.md
@@ -28,7 +28,6 @@ categories:
## Introduction
-
This tutorial is a guide to parsing with nom. It covers the basics of parsing and how to use nom to
parse a string into a data structure. We will cover a variety of different examples ranging from
parsing simple CSS like syntax to a full blown Markdown parser.
@@ -38,6 +37,8 @@ This tutorial has 2 examples in it:
1. [CSS style syntax](#getting-to-know-nom-using-a-simple-example)
2. [Markdown parser](#build-a-markdown-parser)
+{%- include featured.html -%}
+
> For more information on general Rust type system design (functional approach rather than
> object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf)
> by Will Crichton demonstrating Typed Design Patterns with Rust.
@@ -45,7 +46,6 @@ This tutorial has 2 examples in it:
## Documentation
-
nom is a huge topic. This tutorial takes a hands on approach to learning nom. However, the resources
listed below are very useful for learning nom. Think of them as a reference guide and deep dive into
how the nom library works.
@@ -314,7 +314,6 @@ complex parsers. You start w/ the simplest one first, and then build up from the
## Build a Markdown parser
-
> π‘ You can get the source code for the Markdown parser shown in this article from the
> [`r3bl-open-core`](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/src/tui/md_parser)
> repo.
@@ -351,3 +350,5 @@ Here are some entry points into the codebase.
that are used to represent the Markdown document model
([`Document`](https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/tui/md_parser/types.rs))
and all the other intermediate types (`Fragment`, `Block`, etc) & enums required for parsing.
+
+{%- include featured.html -%}
diff --git a/_posts/2023-08-28-justfile.md b/_posts/2023-08-28-justfile.md
index e81390fd..526f9e34 100644
--- a/_posts/2023-08-28-justfile.md
+++ b/_posts/2023-08-28-justfile.md
@@ -38,15 +38,7 @@ with `cargo`.
Before we get started, please take a look at the
[`just` project README](https://github.com/casey/just).
-> π Please star and fork / clone the [r3bl_ansi_color
-> repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/ansi_color) π. We will use
-> this repo as an example to learn how to use `just` to manage project specific commands.
->
-> If you would like to get involved in an open source project and like Rust crates, please
-> feel free to contribute to the [r3bl_ansi_color
-> repo](https://github.com/r3bl-org/r3bl-open-core/contribute). There are a lot of small
-> features that need to be added. And they can be a nice stepping stone into the world of
-> open source contribution π.
+{%- include featured.html -%}
Let's say you have a `justfile` that looks like this, and it has a single recipe called
`list`:
@@ -258,12 +250,4 @@ some interesting links inside the README:
1. [Conditional expressions](https://github.com/casey/just#conditional-expressions).
1. [Setting variables](https://github.com/casey/just#setting-variables-from-the-command-line).
-> π Please star and fork / clone the [r3bl_ansi_color
-> repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/ansi_color) π. We will use
-> this repo as an example to learn how to use `just` to manage project specific commands.
->
-> If you would like to get involved in an open source project and like Rust crates, please
-> feel free to contribute to the [r3bl_ansi_color
-> repo](https://github.com/r3bl-org/r3bl-open-core/contribute). There are a lot of small
-> features that need to be added. And they can be a nice stepping stone into the world of
-> open source contribution π.
+{%- include featured.html -%}
diff --git a/_posts/2023-09-17-tuify-clap.md b/_posts/2023-09-17-tuify-clap.md
index ddbf8f19..781bf7df 100644
--- a/_posts/2023-09-17-tuify-clap.md
+++ b/_posts/2023-09-17-tuify-clap.md
@@ -48,14 +48,7 @@ CLI apps to make them more ergonomic to use. And we can do this without going fu
this in a way that is additive to the existing CLI experience. We can "tuify" our CLI apps that are
built using `clap`.
-> π Please star and fork / clone the
-> [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/tuify) π. We will use this
-> repo as an example to learn how to add minimal interactivity to your clap CLI apps
->
-> If you would like to get involved in an open source project and like Rust crates, please feel free
-> to contribute to the [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/contribute).
-> There are a lot of small features that need to be added. And they can be a nice stepping stone
-> into the world of open source contribution π.
+{%- include featured.html -%}
> For more information on general Rust type system design (functional approach rather than
> object oriented), please take a look at this [paper](https://arxiv.org/pdf/2307.07069.pdf)
@@ -325,11 +318,4 @@ existing CLI experiences. Things like multi line editor component w/ syntax high
scroll view, form input fields, and more. If you would like to contribute to this effort,
it would be great to have your help.
-> π Please star and fork / clone the
-> [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/tuify) π. We will use this
-> repo as an example to learn how to add minimal interactivity to your clap CLI apps
->
-> If you would like to get involved in an open source project and like Rust crates, please feel free
-> to contribute to the [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/contribute).
-> There are a lot of small features that need to be added. And they can be a nice stepping stone
-> into the world of open source contribution π.
+{%- include featured.html -%}
diff --git a/_posts/2023-09-22-overcome-your-fear-of-merge-conflicts.md b/_posts/2023-09-22-overcome-your-fear-of-merge-conflicts.md
index e78bfc12..184dfb90 100644
--- a/_posts/2023-09-22-overcome-your-fear-of-merge-conflicts.md
+++ b/_posts/2023-09-22-overcome-your-fear-of-merge-conflicts.md
@@ -27,7 +27,6 @@ categories:
## Introduction
-
There are few things that generate as much fear and anxiety in developers as `git` merge
conflicts. `git` is very popular and very powerful, and it is a low level command line
tool. And it is not very user friendly. It is meant to be orchestrate-able and automated
@@ -41,6 +40,8 @@ TUIs, or even conversational interfaces.
But that's not the focus of this article which is all about the CLI experience of inducing
and resolving merge conflicts. So let's get started.
+{%- include featured.html -%}
+
## Setting the stage for a merge conflict
@@ -141,11 +142,5 @@ Let's use some pictures to understand the story of how we got here. And how to r
## Next steps
-> If you would like to get involved in an open source project and like Rust crates, please
-> consider contributing to the [r3bl_tuify
-> repo](https://github.com/r3bl-org/r3bl-open-core/contribute). There are a lot of small
-> features that need to be added. And they can be a nice stepping stone into the world of
-> open source contribution π.
->
-> π Please star and fork / clone the
-> [r3bl_tuify repo](https://github.com/r3bl-org/r3bl-open-core/tree/main/tuify) π.
+
+{%- include featured.html -%}
diff --git a/_posts/2024-01-13-write-simple-char-server-in-rust.md b/_posts/2024-01-13-write-simple-char-server-in-rust.md
new file mode 100644
index 00000000..089b1cbd
--- /dev/null
+++ b/_posts/2024-01-13-write-simple-char-server-in-rust.md
@@ -0,0 +1,393 @@
+---
+title: "Write a simple TCP chat server in Rust"
+author: Nazmul Idris
+date: 2024-01-13 15:00:00+00:00
+excerpt: |
+ A guide on how to create write a simple TCP chat server in Rust
+ using Tokio
+layout: post
+categories:
+ - Rust
+ - CLI
+ - Server
+---
+
+
+
+
+
+- [Build a chat server using Tokio](#build-a-chat-server-using-tokio)
+- [The chat server comprises all these pieces](#the-chat-server-comprises-all-these-pieces)
+- [Add dependencies to Cargo.toml](#add-dependencies-to-cargotoml)
+- [Main function](#main-function)
+ - [tokio::spawn does not spawn a new thread, so what does it actually do?](#tokiospawn-does-not-spawn-a-new-thread-so-what-does-it-actually-do)
+- [Handle client task function](#handle-client-task-function)
+ - [Two concurrent tasks in the tokio::select! block](#two-concurrent-tasks-in-the-tokioselect-block)
+ - [Handle read from broadcast channel function](#handle-read-from-broadcast-channel-function)
+ - [Handle socket read function](#handle-socket-read-function)
+- [Next steps](#next-steps)
+
+
+
+## Build a chat server using Tokio
+
+
+In this tutorial we will build a simple chat server using Tokio. The server will be able
+to handle multiple clients, and each client will be able to send messages to the server,
+which will then broadcast the message to all other connected clients.
+
+- We will use Tokio's `tokio::net::TcpListener` and `tokio::net::TcpStream` to create a
+ TCP server that listens for incoming connections and handles them concurrently.
+- We will also use Tokio's `tokio::sync::broadcast` to broadcast messages to all connected
+ clients.
+
+Read [this tutorial]({{ '/2024/01/13/write-simple-netcat-in-rust/' | relative_url}}) to
+learn more about the basics of TCP client and server programming in Rust (without using
+Tokio).
+
+{%- include featured.html -%}
+
+Here's a video of the app that we will build in action.
+
+
+
+> You can find the finished source code for this tutorial
+> [here](https://github.com/nazmulidris/rust-scratch/tree/main/tcp-server-netcat-client).
+
+
+## The chat server comprises all these pieces
+
+
+```text
+ ββCLIENT-1ββββββββ ββCLIENTβ2ββββββββ ββCLIENTβ3βββββββ
+ β β β β β β
+ βββββββββΌβββββββββ ββββββββΌββββββββββ βββββββΌββββββββββ
+ β β β
+ββSERVERββββΌβββββββββββββββββββββββΌβββββββββββββββββββββββββΌβββββββββββββ
+β β β β β
+β β
+β handle_client_task() handle_client_task() handle_client_task() β
+β βββββββββββββββββββββ ββββββββββββββββββββββ βββββββββββββββββββββββ β
+β β ββββββ ββββββ β β ββββββ ββββββ β β ββββββ ββββββ β β
+β β β TX β β RX β β β β TX β β RX β β β β TX β β RX β β β
+β β βββ¬βββ βββ²βββ β β βββ¬βββ βββ²βββ β β βββ¬βββ βββ²βββ β β
+β β β β β β β β β β β β β β
+β βββββββΌβββββββΌβββββββ βββββββΌβββββββΌββββββββ ββββββββΌβββββββΌββββββββ β
+β β β β β β β β
+β β β β β β β β
+β βββββββΌβββββββ΄βββββββββββββββΌβββββββ΄ββββββββββββββββββΌβββββββ΄ββββββββ β
+β β (TX, RX) = channel::broadcast() β β
+β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+The server has a `main` function that creates a `tokio::net::TcpListener` and listens for
+incoming connections. When a new connection is received, it spawns a new task to handle
+the connection using `tokio::spawn()`.
+
+Using `tokio::select!`, the task tries to do the following concurrently, and waits until
+one of them completes:
+1. The task reads messages from its client and broadcasts them to all other connected
+ clients. It also echoes the message back to its client.
+2. The task listens for messages from other clients and sends them to its client.
+
+When one task above completes, the other is dropped. Then the code path with the completed
+task executes. Then the code returns to the infinite loop, if it hasn't returned already.
+
+A client can be any TCP client, such as `telnet`, `nc`, or PuTTY.
+
+## Add dependencies to Cargo.toml
+
+
+Let's create a new project by running `cargo create --bin tcp-server-netcat-client`. Then
+we will add the following dependencies to our `Cargo.toml` file.
+
+```toml
+# tokio.
+tokio = { version = "1.35.1", features = ["full"] }
+
+# stdout logging.
+femme = { version = "2.2.1" }
+log = { version = "0.4.20" }
+
+# r3bl_rs_utils_core - friendly name generator.
+r3bl_rs_utils_core = { version = "0.9.12" }
+r3bl_tui = { version = "0.5.1" }
+```
+
+## Main function
+
+
+We will implement the following algorithm for our server in our main function:
+1. Create a broadcast channel. It will be shared by all the client tasks.
+2. Create `TcpListener` and bind to an address & port.
+3. Loop:
+ - Accept socket connection, and get its `TCPStream`.
+ - Use `tokio::spawn()` to spawn a task to handle this client connection and its
+ `TCPStream`.
+
+In the task that handles the connection:
+1. Get `BufReader` & `BufWriter` from the `TCPStream`. The reader and writer allow us to
+ read data from and write data to the client socket.
+2. Loop:
+ - Use `tokio::select!` to concurrently:
+ - Read from broadcast channel (via `recv()`):
+ - Send the message to the client (only if it is from a different client) over the
+ socket (use `BufWriter` to write the message).
+ - Read from socket (via `BufReader::read_line()`):
+ - Read `incoming` from reader.
+ - Call `process(incoming)` and generate `outgoing`. This colorizes the `incoming`
+ message with a lolcat effect to generate the `outgoing` message.
+ - Send `incoming` message to other connected clients (via the broadcast channel).
+
+> You can find the finished source code for this tutorial
+> [here](https://github.com/nazmulidris/rust-scratch/tree/main/tcp-server-netcat-client).
+
+Here's the code for the main function, and some supporting type aliases and structs:
+
+```rust
+pub type IOResult
+
+
+
+- [Build a Swiss Army knife for networking](#build-a-swiss-army-knife-for-networking)
+- [Add dependencies to Cargo.toml](#add-dependencies-to-cargotoml)
+- [Configure clap to parse command line arguments](#configure-clap-to-parse-command-line-arguments)
+- [Create the client](#create-the-client)
+- [Create the server](#create-the-server)
+- [Next steps](#next-steps)
+
+
+
+## Build a Swiss Army knife for networking
+
+
+In this tutorial we will learn how to use Rust to write a simple netcat client and server
+using the standard library only. A netcat client is like a Swiss Army knife for
+networking. It is similar to PuTTY and telnet. You can use it to connect to a server and
+send and receive data. We will create an app that can behave both as a client and server.
+
+1. Our client will allow the user to type a message and send it to any TCP socket server,
+ and display the response from the server, in an endless loop.
+2. Our server will listen for incoming TCP connections from clients, and display the
+ message from the client, and send a response back to the client.
+
+{%- include featured.html -%}
+
+Here's a video of the app that we will build in action.
+
+
+
+> You can find the finished source code for this tutorial
+> [here](https://github.com/nazmulidris/rust-scratch/tree/main/rtelnet).
+
+## Add dependencies to Cargo.toml
+
+
+Let's create a new project by running `cargo create --bin rtelnet`. Then we will add the
+following dependencies to our `Cargo.toml` file.
+
+```toml
+# Command line argument parsing.
+clap = { version = "4.4.13", features = ["derive"] }
+
+# Pretty logging.
+femme = { version = "2.2.1" }
+log = { version = "0.4.20" }
+
+# Colorization and ANSI escape sequence codes.
+r3bl_tui = { version = "0.5.1" }
+r3bl_ansi_color = { version = "0.6.9" }
+```
+
+## Configure clap to parse command line arguments
+
+
+This Rust app has a single binary, and depending on the command line arguments, it will behave
+either as a client or server. We will use the `clap` crate to parse the command line arguments.
+
+We will configure `clap` so that the following commands will work:
+
+```bash
+cargo run server
+cargo run client
+```
+
+We want to allow the user to specify the following options and chose their own address and
+port. If the user does not specify any options, we will use the default values. The
+default value for `--address` is `127.0.0.1`, and the default value for `--port` is
+`3000`.
+
+```bash
+cargo run server --address 127.0.0.1 --port 8080
+cargo run server --address 127.0.0.1
+cargo run server --port 8080
+
+cargo run client --address 127.0.0.1 --port 8080
+cargo run client --address 127.0.0.1
+cargo run client --port 8080
+```
+
+Let's also add an option that we can use to disable log output to stdout. By default, we
+will log to stdout. But if the user specifies the `--log-disable` flag, then we disable
+all log output.
+
+Here's the clap configuration that gives us this behavior.
+
+```rust
+use clap::{Parser, Subcommand};
+
+pub use defaults::*;
+mod defaults {
+ use super::*;
+
+ pub const DEFAULT_PORT: u16 = 3000;
+ pub const DEFAULT_ADDRESS: &str = "127.0.0.1";
+}
+
+pub use clap_config::*;
+mod clap_config {
+ use super::*;
+
+ #[derive(Parser, Debug)]
+ pub struct CLIArg {
+ /// IP Address to connect to or start a server on
+ #[clap(long, short, default_value = DEFAULT_ADDRESS, global = true)]
+ pub address: IpAddr,
+
+ /// TCP Port to connect to or start a server on
+ #[clap(long, short, default_value_t = DEFAULT_PORT, global = true)]
+ pub port: u16,
+
+ /// Logs to stdout by default, set this flag to disable it
+ #[clap(long, short = 'd', global = true)]
+ pub log_disable: bool,
+
+ /// The subcommand to run
+ #[clap(subcommand)]
+ pub subcommand: CLISubcommand,
+ }
+
+ #[derive(Subcommand, Debug)]
+ pub enum CLISubcommand {
+ /// Start a server on the given address and port
+ Server,
+ /// Connect to a server running on the given address and port
+ Client,
+ }
+}
+```
+
+## Create the client
+
+
+Let's start with the simpler of the two, the client. We will use `std::net::TcpStream` to
+create a TCP socket client. We will need an IP address and port in order to make a TCP
+connection. And to run the client we will need to run the following command:
+
+```bash
+cargo run client
+```
+
+Here's what the main function of our app looks like:
+
+```rust
+fn main() {
+ println!("Welcome to rtelnet");
+
+ let cli_arg = CLIArg::parse();
+ let address = cli_arg.address;
+ let port = cli_arg.port;
+ let socket_address = format!("{}:{}", address, port);
+
+ if !cli_arg.log_disable {
+ femme::start()
+ }
+
+ match match cli_arg.subcommand {
+ CLISubcommand::Server => start_server(socket_address),
+ CLISubcommand::Client => start_client(socket_address),
+ } {
+ Ok(_) => {
+ println!("Program exited successfully");
+ }
+ Err(error) => {
+ println!("Program exited with an error: {}", error);
+ }
+ }
+}
+```
+
+The function that performs the client logic looks like this.
+
+```rust
+fn start_client(socket_address: String) -> IOResult<()> {
+ log::info!("Start client connection");
+ let tcp_stream = TcpStream::connect(socket_address)?;
+ let (mut reader, mut writer) = (BufReader::new(&tcp_stream), BufWriter::new(&tcp_stream));
+
+ // Client loop.
+ loop {
+ // Read user input.
+ let outgoing = {
+ let mut it = String::new();
+ let _ = stdin().read_line(&mut it)?;
+ it.as_bytes().to_vec()
+ };
+
+ // Tx user input to writer.
+ let _ = writer.write(&outgoing)?;
+ writer.flush()?;
+
+ // Rx response from reader.
+ let incoming = {
+ let mut it = vec![];
+ let _ = reader.read_until(b'\n', &mut it);
+ it
+ };
+
+ let display_msg = String::from_utf8_lossy(&incoming);
+ let display_msg = display_msg.trim();
+
+ let reset = SgrCode::Reset.to_string();
+ let display_msg = format!("{}{}", display_msg, reset);
+ println!("{}", display_msg);
+
+ // Print debug.
+ log::info!(
+ "-> Tx: '{}', size: {} bytes{}",
+ String::from_utf8_lossy(&outgoing).trim(),
+ outgoing.len(),
+ reset,
+ );
+ log::info!(
+ "<- Rx: '{}', size: {} bytes{}",
+ String::from_utf8_lossy(&incoming).trim(),
+ incoming.len(),
+ reset,
+ );
+ }
+}
+```
+
+Here are a few things to note about the client code:
+- We create a `BufReader` and `BufWriter` for the `TcpStream` that we get from
+ `TcpStream::connect()`. This is because we want to read and write data in chunks, and
+ not one byte at a time, for performance reasons, and to simplify the logic. These two
+ structs allow us to read and write data very easily in chunks that are delimited by new
+ lines (`\n`).
+- There's a client loop that runs forever. This is because we want to keep the client
+ running forever, so that the user can type a message and send it to the server, and
+ receive a response from the server.
+- How do we exit this infinite client loop? Only when the user presses `Ctrl+C` will the
+ client exit. The [default behavior](https://g.co/bard/share/ac5d3480eb37) for Rust is to
+ exit the process when this happens. This drops the TCP connection causing the server to exit as
+ well.
+- When we read data from user input, it too uses a stream, not a `TcpStream`, but the
+ `stdin()` stream. This behaves very similarly to the `TcpStream` stream. We can read
+ data from it in chunks delimited by new lines (`\n`). Once the user types a message and
+ presses enter that message, eg: `"hi"`, and the new line are stored in the `it`
+ variable, eg: `"hi\n"`. We then convert the String into a byte array, eg: `[104, 105,
+ 10]`, and then convert it into a `Vec is nested inside .
pre {
+ line-height: 1.2;
overflow-x: auto;
> code {
+ line-height: 1.2;
border: 0;
padding-left: 0;
padding-right: 0;
diff --git a/_sass/globals.scss b/_sass/globals.scss
index 469a65b6..13138034 100644
--- a/_sass/globals.scss
+++ b/_sass/globals.scss
@@ -34,8 +34,8 @@ $specialHeadingFontFamily: "Gotham Bold", "Monocraft", "Mabry Pro", "Ndot-55";
$headingFontFamily: "Monocraft", "Mabry Pro", "Gotham Bold", "Spline Sans", "Helvetica Neue", "Google Sans", "Work Sans", Arial, sans-serif;
$baseFontFamily: "Iosevka Term Web", "Victor Mono", "Spline Sans Mono", "Fira Mono", "Fira Sans", "JetBrains Mono", "Helvetica Neue", "Lexend Deca", sans-serif;
-$baseFontSize: 13pt;
-$baseFontWeight: 500;
+$baseFontSize: 12.5pt;
+$baseFontWeight: 400;
$baseLineHeight: 1.6;
$smallFontSize: $baseFontSize * 0.875;
diff --git a/_sass/minima/_base.scss b/_sass/minima/_base.scss
index 34384842..38972f1b 100644
--- a/_sass/minima/_base.scss
+++ b/_sass/minima/_base.scss
@@ -273,7 +273,7 @@ h3 code {
* Sidebar
*/
.sidebar {
- padding: 0 15px 30px 15px;
+ padding: 0 15px 30px 15px;
position: sticky;
top: 0;
}
@@ -356,7 +356,7 @@ table {
@media screen and (min-width: 801px) {
.sidebar {
- padding: 30px;
+ padding: 30px;
max-width: 330px;
}
diff --git a/assets/chatserver-hero.svg b/assets/chatserver-hero.svg
new file mode 100644
index 00000000..bfea3544
--- /dev/null
+++ b/assets/chatserver-hero.svg
@@ -0,0 +1,108 @@
+
diff --git a/assets/chatserver.svg b/assets/chatserver.svg
new file mode 100644
index 00000000..d2fec6a0
--- /dev/null
+++ b/assets/chatserver.svg
@@ -0,0 +1,86 @@
+
diff --git a/assets/netcat-hero.svg b/assets/netcat-hero.svg
new file mode 100644
index 00000000..a56ba70c
--- /dev/null
+++ b/assets/netcat-hero.svg
@@ -0,0 +1,108 @@
+
diff --git a/assets/netcat.svg b/assets/netcat.svg
new file mode 100644
index 00000000..c182e37c
--- /dev/null
+++ b/assets/netcat.svg
@@ -0,0 +1,86 @@
+