Rust is a systems programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety.

rust

In this course, Chris takes a README-driven approach to build out a Rust CLI that supports content authoring for a digital garden.

Specifically, you'll work through the first command for the CLI, writing files. You start by initializing a new Cargo binary crate through creating the `write` command that allows you to create files (and their contents) to the folder that you set. 

Step by step you'll learn about:
- Handling user input
- Error handling
- Rust Move semantics
- Rust Copy semantics
- Integration testing

...and more!

Maggie Appleton

By writing the README first we can explore different
approaches to the user experience of our CLI. We
could think through the entire CLI right now, but we'll
leave other subcommands for later. Instead, we'll focus
on the fact that we know we will have multiple subcommands
and design the command on which all others rely: `write`.

We can come up with a first example subcommand. Note that
by doing this we are also defining the name of the binary
as `garden`.

```shell
garden write
```

When writing, users will not necessarily know the title of
what they're writing in advance, so we will not require
them to provide it. This leads us to an optional title
argument. We could have chosen to make this a positional
argument, but we made it a flag instead to delineate from
other potential future positional arguments (such as
`--message`, which we have chosen not to implement now).

```shell
garden write -t "Writing about Rust"
```

README-driven planning for a Digital Garden CLI in Rust

```shell
cargo init
```

By default cargo initializes a new package containing a *binary* crate.
The file that gets compiled into the binary is located at
`src/main.rs`. This is by convention and we can specify different paths
and names for binaries.

We also get a `Cargo.lock` and a `Cargo.toml`. These are similar to
JavaScript's `package.json` and `package-lock.json` or `yarn.lock`.
The `Cargo.toml` defines different features of our package including
`dependencies`, defining zero or one library crates, and defining as
many binary crates as we want.

We can run the new binary with `cargo run`.

```shell
❯ cargo run
   Compiling digital-garden-steps v0.1.0 (/digital-garden-steps)
    Finished dev [unoptimized + debuginfo] target(s) in 1.38s
     Running `target/debug/digital-garden-steps`
Hello, world!
```

Initialize a new Cargo binary crate in a new package

In `./target/debug/` we can see the binary name:
`digital-garden-steps`. This is the name of our package
and we want the actual binary that users install to be
named `garden` instead.

To do this we can change the auto-discovered `src/main.rs`
binary and change the name using a `bin` config in the
`Cargo.toml` file.

```toml
[[bin]]
name = "garden"
path = "src/main.rs"
```

Then we see `./target/debug/garden` get created when we
`cargo run` or `cargo build`.

Rename the default Cargo binary to be different than the package name

We'll replace the `println!` macro with a call to `todo!`, which has
the additional benefit of type-checking so we won't need to finish
anything with `todo!` in the expression. Note that if we call a function
with `todo!`, we do get the `panic!` behavior.

We do have two other options for achieving the same thing,
`unimplemented!` and `panic!`. All three of these options functionally
do the same thing: they crash the program immediately.

We aren't using `panic!` because `panic!` should be used when a program
reaches an unrecoverable state. We don't have an unrecoverable state
so much as a piece of the program we intend to work on later.

For similar reasons, we aren't using `unimplemented!` because we want
to convey that this is something to work on while `unimplemented!`
doesn't necessarily mean that we intend to work on it.

Using the todo macro to typecheck unwritten code that will be implemented in the future

Right now we are using the `todo!()` macro which is great for simulating when our program panics. The error message that we get can be improved upon.

We will look at color-eyre that will allow us to handle the errors we receive to be more visual and human-readable. 

---
The `todo!` macro is useful and it also exposes what
happens if our application panics.

```
thread 'main' panicked at 'not yet implemented', src/main.rs:2:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```

This could be both more readable and contain more information
while also being colored using [color_eyre](https://docs.rs/color-eyre/0.5.10/color_eyre/).

```
The application panicked (crashed).
Message:  not yet implemented
Location: src/main.rs:5

Backtrace omitted.
Run with RUST_BACKTRACE=1 environment variable to display it.
Run with RUST_BACKTRACE=full to include source snippets.
```

We'll use [cargo-edit](https://crates.io/crates/cargo-edit)
to add the package to our Cargo.toml.

```
cargo install cargo-edit
cargo add color_eyre
```

`main` can return `Result`, so we'll use `color_eyre`'s
`Result` as our return value and `color_eyre::install` to
install the default panic and error reporting hooks.
`install` returns a `Result` so we can use `?` to handle
any errors if necessary.

We haven't shown off everything that color_eyre is capable
of. In addition to panic handling, color_eyre allows us to
track additional information in the context of our errors
and include suggestions by taking advantage of distributed
[tracing](https://github.com/tokio-rs/tracing) infrastructure.

We'll see more of how this helps as we build out the CLI.

Using color_eyre and distributed tracing to yield better error messages to the user

The StructOpt crate allows us to derive our human person functionality from our Struct definitions. 

We will create a `structop` for our `write` subcommand that will take a short and long flag for our `title` argument

---

```
cargo add structopt
```

structopt allows us to derive argument parsing functionality from our
structs. The name is a play on `struct Opt {}`. To do this we need to
`derive(StructOpt)` on our struct. In this case we have a subcommand,
so we'll set up one of the fields on the `Opt` struct to be a
`structopt(subcommand)`. This subcommand value will be an enum,
indicating that only one subcommand can be used at a time.

structopt also gives us tools to specify one of three argument types:

* positional
* short
* long

By default every argument is a positional argument, which means that in
this case if we left it as-is, the CLI would function as

```
garden write my-title
```

We want to use a flag, so we'll use structopt to generate short and long
flags for the title argument with `structopt(short, long)`. That gives
the use the option of `-t` and `--title` to specify a title.

structopt also contains some type processing, so all we need to do is
specify that title is an optional string and the flags will become
optional. That is: a user can specify or not specify a title.

```rust
struct Opt {
    #[structopt(subcommand)]
    cmd: Command,
}
enum Command {
    Write {
        #[structopt(short, long)]
        title: Option<String>,
    },
}
```

After setting up `struct Opt`, we can parse the args and use
the dbg!() macro to print them to the console so we can see
what they look like.

```rust
let opt = Opt::from_args();
dbg!(opt);
```

To do that we also need to `derive(Debug)` in addition to
structopt on both the enum and the struct.

Given input like

```
garden write
```

We will see the following output.

```rust
[src/main.rs:21] opt = Opt {
    cmd: Write {
        title: None,
    },
}
```

We can choose to `cargo build` and then `./target/debug/garden write`
or we can use `cargo run -- write`. The `--` ensures that our arguments
get passed to the CLI we're building and not `cargo run`. This is
especially relevant when passing something like `--help`.

Setting up git-like subcommands using structopt

if we run `cargo run -- --help`, we can see that structopt
thinks the name of our binary is still the package name.
We can change that with another attribute macro on our
struct.

```
digital-garden 0.1.0

USAGE:
    garden <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help     Prints this message or the help of the given subcommand(s)
    write
```

Also notice that in the help text the `help` subcommand
has some helpful output while `write` has none:

```
garden 0.1.0

USAGE:
    garden <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help     Prints this message or the help of the given subcommand(s)
    write
```

There are a number of places we can put doc comments.
We can write on the `Opt` struct for global information
about the CLI.

We can also write on each subcommand or even the options
for each subcommand.

```
/// A CLI for the growing and curation of a digital garden
///
/// Visit https://www.rustadventure.rs/garden for more!
struct Opt {
    #[structopt(subcommand)]
    cmd: Command,
}
enum Command {
    /// write something in your garden
    ///
    /// This command will open your $EDITOR, wait for you
    /// to write something, and then save the file to your
    /// garden
    Write {
        /// Optionally set a title for what you are going to write about
        #[structopt(short, long)]
        title: Option<String>,
    },
}
```

Each of these results in documentation going to the relevant
place in the CLI help text. Note especially that the first
line of doc comment for subcommands is shown as "short"
help text, while the full text is reserved for running
`--help` directly on the subcommand.

```
❯ cargo run
garden 0.1.0
A CLI for the growing and curation of a digital garden

Visit https://www.rustadventure.rs/garden for more!

USAGE:
    garden <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help     Prints this message or the help of the given subcommand(s)
    write    write something in your garden
```

```
❯ cargo run -- write --help
garden-write 0.1.0
write something in your garden

This command will open your $EDITOR, wait for you to write something, and then save the file to your garden

USAGE:
    garden write [OPTIONS]

FLAGS:
    -h, --help
            Prints help information

    -V, --version
            Prints version information

OPTIONS:
    -t, --title <title>
            Optionally set a title for what you are going to write about
```

Also note that `-h` and `--help` are *not* the same thing when it comes to structopt.

Documenting and writing helptext for Structopt CLI commands and flags

Cargo allows us to execute a few different kinds of tests,
including integration and unit. For now we'll talk about
integration tests for our CLI. Integration tests
live in `/tests` and only have access to the public
interface of a crate.

In this case, we'll run the `garden` binary using
`assert_cmd` and assert various things about the
execution and output. For example, that the binary
exits successfully and that stderr has no output.

`cargo test` allows us to run all tests.

To restrict the number of tests that run to only the two
that work, we can use `cargo test help` to restrict
cargo to only running tests that match the keyword "help",
or use `#[ignore]` on a test we want to ignore.

The third test will be ignored because we have yet to
build out our functionality.

Integration testing Cargo binaries with assert_cmd

We can match on `opt.cmd` to determine which `Command`
variants was called. This lets us specify the variants
as match criteria and also destructure the values out
to use them.

```rust
    let opt = Opt::from_args();
    dbg!(&opt);
    match opt.cmd {
        Command::Write { title } => todo!(),
    }
```

As written, we run into two issues with this code.
One is that we aren't using `title` yet. In
destructuring, we can use the placeholder (`_`) in our
[pattern](https://doc.rust-lang.org/reference/patterns.html).

```
warning: unused variable: `title`
  --> src/main.rs:32:26
   |
32 |         Command::Write { title } => todo!(),
   |                          ^^^^^ help: try ignoring the field: `title: _`
   |
   = note: `#[warn(unused_variables)]` on by default
```

```rust
fn main() -> Result<()> {
    color_eyre::install()?;

    let opt = Opt::from_args();
    dbg!(opt);
    match opt.cmd {
        Command::Write { title: _ } => todo!(),
    }
}
```

The second issue is that the `opt` variable is moved
before we try to destructure it. If we look at the
compiler output before we fixed the `title` issue we
see the value use after move pointing at `title`
specifically.

```
error[E0382]: use of moved value
m  --> src/main.rs:32:26
   |
29 |     let opt = Opt::from_args();
   |         --- move occurs because `opt` has type `Opt`, which does not implement the `Copy` trait
30 |     dbg!(opt);
   |     ---------- value moved here
31 |     match opt.cmd {
32 |         Command::Write { title } => todo!(),
   |                          ^^^^^ value used here after move
```

If we look at it after fixing the unused `title`,
we see the compiler point at `opt.cmd`.

```
error[E0382]: use of moved value: `opt.cmd`
  --> src/main.rs:31:11
   |
29 |     let opt = Opt::from_args();
   |         --- move occurs because `opt` has type `Opt`, which does not implement the `Copy` trait
30 |     dbg!(opt);
   |     ---------- value moved here
31 |     match opt.cmd {
   |           ^^^^^^^ value used here after move
```

This is because opt is moved into the `dbg` call because
it doesn't implement the `Copy` trait. Now, we could
implement or derive `Copy` for `Opt` if `Command` can
implement `Copy`, but we can not implement `Copy` for
`Command`. This is because `String` does not, and can not,
implement `Copy`, and we have a `String` in our `title`.

Without diving into the depths of `Copy`, [`Clone`](https://doc.rust-lang.org/std/clone/trait.Clone.html),
and allocation, there is something we have that already
implements `Copy`, so we don't need to.

Shared references implement `Copy`.

So instead of passing `opt` into `dbg!`, and thus using
move semantics (which are the default in Rust), we can
pass a shared reference in: `dgb!(&opt)` which lets us
use copy semantics.

The difference between move semantics and copy semantics
in this case is that we can access `opt` after passing it
to `dbg!`.

Under the hood, both a copy and a move can result in bits
being copied in memory, although this is sometimes
optimized away. -- [Copy](https://doc.rust-lang.org/std/marker/trait.Copy.html)

```rust
fn main() -> Result<()> {
    let opt = Opt::from_args();
    dbg!(&opt);
    match opt.cmd {
        Command::Write { title: _ } => todo!(),
    }
}
```

Matching structopt commands and using Rust values after move

In our subcommand match we'll add a new function called
`write` to handle our `Write` subcommand. We'll pass it
the argument title and we'll "import" it from a library
called `digital_garden`. 

```rust
use digital_garden::write;

fn main() -> Result<()> {
    color_eyre::install()?;

    let opt = Opt::from_args();
    dbg!(&opt);
    match opt.cmd {
        Command::Write { title } => write(title),
    }
}
```

To create this library, add a new section in `Cargo.toml`.
We can give our library a name and set which file to treat
as the entrypoint. `src/lib.rs` is the default file for
a library crate, but we can also be explicit about what we
want to happen.

```toml
[lib]
name = "digital_garden"
path = "src/lib.rs"
```

This leaves us with two crates, a binary crate, of which we
can have any amount, and a library crate, of which we can
only have 0 or 1.

We'll create the `src/lib.rs` file with the following
contents.

```rust
mod write;

pub use write::write;
```

Rust's module system is explicit, so when we write
`mod write`, we are saying that the library `digital_garden`
has a module `write`, such that the path to the module is
`digital_garden::write`.

In our case `digital_garden::write` corresponds to a file
at `src/write.rs`.

Secondly, the `pub use write::write` says that we have a
function called `write` in the module called `write` and
that the function will be exposed from lib publicly, so
people who have the `digital_garden` library installed
will be able to use the write function as
`digital_garden::write`.

In JavaScript the closest analogue is exporting a function
from another file that exports it.

```js
export { write } from './write.js';
```

By using use, we're shortening the public path to the write
function. A private module "write" with a function "write"
also exists at `digital_garden::write::write`. If you try
to use this path, Rust will tell you there is a private
module there.

Finally, in `src/write.rs`, we can write a public function
that matches the return type of our main function, since
we're using it as the return value from our match function.

We'll accept an `Option<String>` as an argument as well,
since that's what we expect from the cli arguments.

```rust
use color_eyre::Result;

pub fn write(_title: Option<String>) -> Result<()> {
    todo!()
}
```

The purpose of creating this module path is because we
know that we're going to set up more modules for each
subcommand in the future, and we can control both the
placement of our code on disk, as well as the path users
will interact with to use our module.

Creating a library crate to support a Rust binary crate in the same package

We want to build out functionality to let the user
write into a file in their garden. To do that, we
have to know the location of their garden.

We'll start by implementing a function to get the
default garden path.

```rust
fn get_default_garden_dir() -> Result<PathBuf> {
    let user_dirs = UserDirs::new().ok_or_else(|| eyre!("Could not find home directory"))?;
    Ok(user_dirs.home_dir().join(".garden"))
}
```

This uses the user's system directories via the
`directories` crate to find their home dir. We
then add `.garden` to the home dir for the default
garden.

Ideally, we would want the user to be able to
specify their garden path. Using structopt, we
can let them specify it as a short, long, or
env var.

In our README, we'll specify how this should work.

````

```shell
GARDEN_PATH=~/github/my-digital-garden garden write
garden -p ~/github/my-digital-garden write
garden --garden_path ~/github/my-digital-garden write
```
````

And in our `Opt` struct, we can tell structopt how to
handle it. Putting this in our `Opt` struct instead of
our `Command` enum make it a global flag that can be
specified for all subcommands.

```rust
struct Opt {
    #[structopt(parse(from_os_str), short = "p", long, env)]
    garden_path: Option<PathBuf>,

    #[structopt(subcommand)]
    cmd: Command,
}
```

structopt is only handling the user input, so in
`main()` we still need to fall back to the
default if the `garden_path` is not specified.

```rust
let garden_path = match opt.garden_path {
    Some(pathbuf) => Ok(pathbuf),
    None => get_default_garden_dir().wrap_err("`garden_path` was not supplied"),
}?;
```

if we force an `Err` in `get_default_garden_dir`
We can see how the wrapped errors end up stacking.

```
Error:
   0: `garden_path` was not supplied
   1: Could not find home directory
```

We'll also change the signature of `write` to
accept the pathbuf.

```
Command::Write { title } => write(garden_path, title),
```

Note that we need to import `PathBuf`. We can also
`dbg!` the garden path and title to see their
values.

```rust
use std::path::PathBuf;

pub fn write(garden_path: PathBuf, title: Option<String>) -> Result<()> {
    dbg!(garden_path, title);
    todo!()
}
```

Adding support for global flags that apply for all subcommands with structopt

What user experience do we want for the
act of writing?

We have a few options, including letting
users write directly in the console or giving
them a prepared file that they can then open
and write in.

Writing directly in the console doesn't give
a user access to their text editor of choice.
Which means lacking autocomplete, syntax
highlighting, snippets, and other functionality.

Creating a file and handling the path back to
the user doesn't quite work for us either, as
that reduces the utility of the garden write
command to the equivalent of running `touch
filename.md`.

So for our use case, we'd ideally like to open
the user's preferred editing environment,
whatever that happens to be, then wait for them
to be done with the file before continuing.

Since we're working with a CLI tool, we
can safely assume that our users either
know how to, or are willingly to learn how
to, set environment variables. This means we
can use the `EDITOR` variable to select an
editor to use. This is the same way `git commit`
works.

---

In Rust, there is a crate that handles not only
`EDITOR`, but also various fallbacks per-platform.
We'll take advantage of [edit](https://crates.io/crates/edit)
to call out to the user's choice of editor.

The quick usage of edit allows us to call the
`edit::edit` function, and get the user's data.

```rust
pub fn write(garden_path: PathBuf, title: Option<String>) -> Result<()> {
    dbg!(garden_path, title);
    let template = "# ";
    let content_from_user = edit::edit(template).wrap_err("unable to read writing")?;
    dbg!(content_from_user);
    todo!()
}
```

This results in a filename that looks like:
`.tmpBy0Yun` "somewhere else" on the filesystem,
in a location the user would never reasonably
find it. Ideally, if anything went wrong, the
user would be able to take a look at the
in-progress tempfile they were just working on,
which should be in an easily discoverable place
like the garden path.

*We don't want to lose a user's work.*

Additionally, the tempfile doesn't have a file
extension, which means that the user's editor
will be less likely to recognize it as a
markdown file, so we want to add `.md` to the
filepath.

```rust
use color_eyre::{eyre::WrapErr, Result};
use edit::{edit_file, Builder};
use std::io::{Read, Write};
use std::path::PathBuf;

const TEMPLATE: &[u8; 2] = b"# ";

pub fn write(garden_path: PathBuf, title: Option<String>) -> Result<()> {
    let (mut file, filepath) = Builder::new()
        .suffix(".md")
        .rand_bytes(5)
        .tempfile_in(&garden_path)
        .wrap_err("Failed to create wip file")?
        .keep()
        .wrap_err("Failed to keep tempfile")?;
    file.write_all(TEMPLATE)?;
    // let the user write whatever they want in their favorite editor
    // before returning to the cli and finishing up
    edit_file(filepath)?;
    // Read the user's changes back from the file into a string
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;

    dbg!(contents);
    todo!()
}
```

We will use the `edit::Builder` API to generate
a random tempfile to let the user write content
into. The suffix is going to be `.md` and the
filename will be 5 random bytes. We also put
the tempfile in the garden path, which ensures
a user will be able to find it if necessary.

`wrap_err` (which requires the `eyre::WrapErr`
trait in scope) wraps the potential error
resulting from these calls with additional context,
making the original error the source, and we can
keep chaining after that. We `keep` the tempfile,
which would otherwise be deleted when all handles
closed, because if anything goes wrong after the
user inputs data, we want to make sure we don't
lose that data.

After the file is created, we write our template
out to the file before passing control to the
user. This requires the `std::io::Write` trait
in scope. We use a const for the file template
because it won't change. To make the `TEMPLATE`
a const, we also need to give it a type, which
is a two element byte array. Change the string
to see how the byte array length is checked at
compile time.

Since we have access to the `file` already, we
can read the contents back into a string after
the user is done editing. This requires having
the `std::io::Read` trait in scope.

And now we've let the user write into a file
which will stick around as long as we need it
to, and importantly will stick around if any
errors happen in the execution of the program,
so we lose no user data and can remove the
temporary file at the end of the program
ourselves if all goes well.

Passing control to the user's favorite editor (such as VSCode) from the CLI

After getting the user's input, we need to
figure out a filename to write the file out
as. We can either use the title the user
passed in, or we can try to use heuristics
to find a title from the markdown content.

We can combine the user's title from the cli
arguments (an `Option`) with the logic we
use as a heuristic for the markdown (also
an `Option`).

```rust
// use `title` if the user passed it in,
// otherwise try to find a heading in the markdown
let document_title = title.or_else(|| {
    contents
        .lines()
        .find(|v| v.starts_with("# "))
        // markdown headings are required to have `# ` with
        // at least one space
        .map(|maybe_line| maybe_line.trim_start_matches("# ").to_string())
});
```

`option.or_else()` returns the original
option if it is a `Some` value, or executes
the function to return a different `Option`
if not. So `document_title` is an
`Option<String>` either way and we've
covered all of the possible scenarios:

1. the user has passed in a title
2. the user has written content with a heading
3. the user has done neither of these

Which leaves us to our markdown heuristic.

Markdown headings are required to have `# `
with at least one space, so we can turn
`contents` into an iterator and `find` the
first line that starts with `# `.

If we find one, we want to trim `# ` off of
the heading to get just the heading content,
so we can use `map` to operate on the value
inside of the `Option` returned by `find` if
it exists.

```rust
contents
    .lines()
    .find(|v| v.starts_with("# "))
    .map(|maybe_line| maybe_line.trim_start_matches("# ").to_string())
```

Now this code works fine, but it exposes a bug
in our file handling.

If we `write_all` to the `file`, that moves the
internal cursor to the end of that content. So
when we run our code now, `contents` is
skipping the first `# ` bytes, which means our
heuristic will only find the second heading in
the file.

To fix this, we can bring in the `std::io::Seek`
trait, and seek to the beginning of the file.

```rust
let mut contents = String::new();
file.seek(SeekFrom::Start(0))?;
file.read_to_string(&mut contents)?;
```

Using the Option type in Rust to pick from multiple values that might not exist

Given the potential `document_title` we now
want to ask the user if the title is still
what they want to use so that we can write
the file to disk. This will involve two
paths depending on if we have an existing
potential option or not.

We will need to use `ask_for_filename` in
`confirm_filename`, so we'll write that branch
first.

```rust
let filename = match document_title {
    Some(raw_title) => {
        // confirm_filename()?
        todo!()
    }
    None => ask_for_filename(),
};
```

`rprompt` allows us to ask for a small amount
of input from the user (compared to the  much
larger input possible by passing control to
the user's editor).

We'll use `rprompt::prompt_reply_stderr` to
get a response from the user, and `.wrap_err`
to add context to the error if anything goes
wrong.

```rust
fn ask_for_filename() -> Result<String> {
    rprompt::prompt_reply_stderr(
        "\
Enter filename
> ",
    )
    .wrap_err("Failed to get filename")
}
```

We'll use the same behavior for the first
part of `confirm_filename`. We'll also
need to use our first lifetime to account
for the shared reference argument.

`match` can match against multiple values
for the same branch, so we'll take advantage
of that to handle branches for Ns and Ys, as
well as the default case. If anything goes
wrong, such as someone inputting an "a",
we'll fall through using `loop` and ask again
until we get a usable answer

```rust
fn confirm_filename(raw_title: &str) -> Result<String> {
    loop {
        // prompt defaults to uppercase character in question
        // this is a convention, not a requirement enforced by
        // the code
        let result = rprompt::prompt_reply_stderr(&format!(
            "\
current title: `{}`
Do you want a different title? (y/N): ",
            raw_title,
        ))
        .wrap_err("Failed to get input for y/n question")?;

        match result.as_str() {
            "y" | "Y" => break ask_for_filename(),
            "n" | "N" | "" => {
                // the capital N in the prompt means "default",
                // so we handle "" as input here
                break Ok(slug::slugify(raw_title));
            }
            _ => {
                // ask again because something went wrong
            }
        };
    }
}
```

While filenames can technically have spaces
in them, we're going to slugify our filenames
like urls for a few reasons. One is that
when starting out, many programmers fail to
quote filename arguments in their bash scripts,
which results in filenames with spaces being
treated as separate arguments. Another is
that this is a digital garden CLI, and
digital gardens are often stored in git,
accessed from multiple file systems, as well
as from URLs. While strictly speaking we don't
need to slugify our filenames, we will here
so as to adhere to a safer set of characters.

```
cargo add slug
```

We'll map over the `Result` from `rprompt`
which allows us to operate on the internal
value if it's `Ok`.

```rust
fn ask_for_filename() -> Result<String> {
    rprompt::prompt_reply_stderr(
        "\
Enter filename
> ",
    )
    .wrap_err("Failed to get filename")
    .map(|title| slug::slugify(title))
}
```

We'll also use slugify in `confirm_filename`

```rust
match result.as_str() {
    "y" | "Y" => break ask_for_filename(),
    "n" | "N" | "" => {
        // the capital N in the prompt means "default",
        // so we handle "" as input here
        break Ok(slug::slugify(raw_title));
    }
    _ => {
        // ask again because something went wrong
    }
};
```

The fact that `confirm_filename` and
`ask_for_filename` have the same return type
is important because the branches of a `match`
need to return the same type.

Prompting the user for input with rprompt and loop

`PathBuf` lets us check to see if a file
exists before writing to it, so we can
take advantage of that to make sure that
we don't overwrite a file that already
exists, even if the user has indicated
a title that would overwrite another file.

```
let mut i: usize = 0;
loop {
    let dest_filename = format!(
        "{}{}",
        filename,
        if i == 0 {
            "".to_string()
        } else {
            i.to_string()
        }
    );
    let mut dest = garden_path.join(dest_filename);
    dest.set_extension("md");
    if dest.exists() {
        i = i + 1;
    } else {
        fs::rename(garden_tmpfile, &dest)?;
        break;
    }
}
```

Checking for file existence with PathBuf to ensure unique filenames

We can print lines to the terminal and
ask the user for various input. So let's
make the interface a bit more usable by
using colored output.

We can do this by bringing an extension
trait for formatting into scope:
`OwoColorize`.

Extension traits are one-off traits that
are used to add functions to a type that
our crate doesn't own. A crate can create
the new trait, then implement the
functions defined by that trait on a type
the crate doesn't own and if we bring that
trait into scope, the type will get the
extra functions. In this case, `OwoColorize`
is used for adding color functions to
formatters like Display and Debug.

We'll start with `ask_for_filename`

```rust
use color_eyre::owo_colors::OwoColorize;

fn ask_for_filename() -> Result<String> {
    rprompt::prompt_reply_stderr(&format!(
        "{}",
        "\
Enter filename
> "
        .blue()
        .bold(),
    ))
    .wrap_err("Failed to get filename")
    .map(|title| slug::slugify(title))
}
```

In `confirm_filename` we can use multiple
formatters to get different colors:

```rust
let result = rprompt::prompt_reply_stderr(&format!(
    "\
{} {}
Do you want a different title? (y/N): ",
    "current title:".green().bold(),
    raw_title,
))
.wrap_err("Failed to get input for y/n question")?;
```

Using owo_colors Extension Traits to colorize terminal output

We have been ignoring implementing tests for the write subcommand. Now is the time that we'll test the command we have been building.

We'll build out a fake editor script that our test will use to check if the command is functioning properly. We will then use `arg` to build the command as we would normally use it ourselves.

After writing the test, we'll see how to clean up after ourselves so that we aren't leaving testing artifacts leftover just from running a test.

---

How to integration test a cargo binary that calls
out to `EDITOR` for modifications and asks the
user for input.

First we'll create a fake editor script to use
instead of vim, etc.

`tests/fake_editor.sh` is a one-liner.

```shell
echo "testing" >> $1;
```

Then we'll write our test using `assert_cmd` to
build up a `Command` that points to the `garden`
binary in out `Cargo.toml`.

We grab the fake editor path script using
`std::env::current_dir()`, make sure the file
exists (which means we've grabbed the right
path), and spawn a new `Command` with the
`EDITOR` variable set to the fake editor
script. The equivalent call to our bin is

```shell
EDITOR=path/to/fake-editor.sh garden write -t atitle
```

And the rust code to execute.

```rust
fn test_write_with_title() {
    let mut cmd = Command::cargo_bin("garden").unwrap();
    let fake_editor_path = std::env::current_dir()
        .expect("expect to be in a dir")
        .join("tests")
        .join("fake-editor.sh");
    if !fake_editor_path.exists() {
        panic!(
            "fake editor shell script could not be found"
        )
    }

    let assert = cmd
        .env("EDITOR", fake_editor_path.into_os_string())
        .arg("write")
        .arg("-t")
        .arg("atitle")
        .write_stdin("N\n".as_bytes())
        .assert();

    assert.success();
}
```

Note that we're asserting that the command
exited sucessfully, and that we're inputing
`N\n` to the bin's stdin, which responds to
a request for user input after the editor
closes.

Note that this doesn't actually test for
the resulting file existence, and also that
we're writing our files out directly into
our default digital garden! We can solve
this with `assert_fs` and `predicates`.

We'll bring in both preludes (a prelude is
a bunch of stuff the library author thinks
will be useful to have around all the time)
and create a new temporary directory.

We'll use the `GARDEN_PATH` environment
variable to pass the temporary directory in
to the `garden` bin and that's it, we've
added a temporary directory to our test.
No more polluting the default garden!

```rust
use assert_fs::prelude::*;
use predicates::prelude::*;

fn test_write_with_title() {
    let temp_dir = assert_fs::TempDir::new().unwrap();

    let mut cmd = Command::cargo_bin("garden").unwrap();
    let fake_editor_path = std::env::current_dir()
        .expect("expect to be in a dir")
        .join("tests")
        .join("fake-editor.sh");
    if !fake_editor_path.exists() {
        panic!(
            "fake editor shell script could not be found"
        )
    }

    let assert = cmd
        .env("EDITOR", fake_editor_path.into_os_string())
        .env("GARDEN_PATH", temp_dir.path())
        .arg("write")
        .arg("-t")
        .arg("atitle")
        .write_stdin("N\n".as_bytes())
        .assert();

    assert.success();

    temp_dir
        .child("atitle.md")
        .assert(predicate::path::exists());
}
```

Now that's enough, but we can also check
to make sure the file we expect to exist
actually exists. `temp_dir.child` gives
us the possible file, and we can assert
on that file with a test from `predicates`
that tests to make sure the file exists.

```rust
temp_dir
    .child("atitle.md")
    .assert(predicate::path::exists());
```

Using assert_fs and predicates to integration test with a real temporary file system

While we have `test_write_with_title`
which tests the garden CLI with a given
title flag, we can also set up additional
tests, such as for using a written title
in the document for the filename.

Copy/pasting the code from test one into
test two is a lot of duplication, and
setting up the fake editor isn't going
to change across tests, so let's abstract
the creation of the temporary directory,
the fake editor script path, and the
`Command` itself into a utility function.

The port is relatively straightforward,
with the only changes being that we cut
off the `cmd` modifications before the
`.arg` calls, and now have to return
the `cmd` and the `temp_dir` in a tuple.

We return the actual `Command` and `TempDir`,
yielding ownership to the calling function
because we have no further use for them here,
but the calling function will need to mutate
the `Command` more, and use `TempDir` to test.

```rust
fn setup_command() -> (Command, assert_fs::TempDir) {
    let temp_dir = assert_fs::TempDir::new().unwrap();

    let mut cmd = Command::cargo_bin("garden").unwrap();
    let fake_editor_path = std::env::current_dir()
        .expect("expect to be in a dir")
        .join("tests")
        .join("fake-editor.sh");
    if !fake_editor_path.exists() {
        panic!(
            "fake editor shell script could not be found"
        )
    }

    cmd.env("EDITOR", fake_editor_path.into_os_string())
        .env("GARDEN_PATH", temp_dir.path());
    (cmd, temp_dir)
}
```

The new write tests are considerably shorter
now and focus mostly on which subcommand to
call, and what the user interaction with that
subcommand is.

```rust

fn test_write_with_title() {
    let (mut cmd, temp_dir) = setup_command();
    let assert = cmd
        .arg("write")
        .arg("-t")
        .arg("atitle")
        .write_stdin("N\n".as_bytes())
        .assert();

    assert.success();

    temp_dir
        .child("atitle.md")
        .assert(predicate::path::exists());
}

fn test_write_with_written_title() {
    let (mut cmd, temp_dir) = setup_command();
    let assert = cmd
        .arg("write")
        .write_stdin("N\n".as_bytes())
        .assert();

    assert.success();

    temp_dir
        .child("testing.md")
        .assert(predicate::path::exists());
}
```

Abstracting test utilities inside integration test files

This course takes you from a blank app to learning about types, config files, and the cargo package manager along with topics like functions, loops and handling user input.

Write Your First Program with the Rust Language

This course walks you through Rustlings exercises in a way that explains what's going on in each exercise. We cover everything from basic types to generics and threading.

Learning Rust by Working Through the Rustlings Exercises

This collection contains videos that explore in-depth the basic types that you use in Rust.

Basic Types in Rust

Creating a Digital Garden CLI with Rust

https://app.egghead.io/api/v1/lessons/rust-readme-driven-planning-for-a-digital-garden-cli-in-rust/subtitles

Instructor: [0:00] by writing the readme first, we can explore different approaches the user experience of our CLI. We could think through the entire CLI right now.

[0:10] We'll leave other subcommands for later. Instead, focus on the fact that we know that we will have multiple subcommands in this course and design the command on which all the other ones rely.

[0:20] By focusing on the README, we'll focus on the experience of the users who want to use our tool. In this case, the first thing that we'll hit is the title Digital Garden, which is the name of our tool, and description, a CLI tool for the creation and maintenance of Digital Garden.

[0:43] Now I've already written this course, so I know that we're going to have multiple subcommands. When we think about how somebody is going to write in their Digital Garden, we can think about the things that they are going to want to do. They want to write something. They want to search their documents for specific tags or maybe want to publish a site from those documents.

[1:02] We can immediately see there are multiple separate actions where you're going to want to take on a digital garden. The most basic action we'll want to take is to just write something. In this case, our CLI name is going to be Garden because it's fairly easy to type. It's six letters. It's a lot shorter than typing out digital-garden.

[1:21] The subcommand we're going to use to write is called Write. We've already defined the name of the binary that we're going to use by writing the readme. Thinking about what else we might want to do with this write command, we might already know what we're going to write about.

[1:35] I might want to write about, say, iterators in Rust, in which case, I'll want to give the command a title when I say that I'm going to write. In other cases, I may be taking notes, or I may not know what I'm going to write yet or what I should title it.

[1:49] We'll make sure that the right subcommand can accept the -t or --title flag with the title that we'll use to create the file name with the content that the user ends up writing.

[2:01] I'll add a description here and fix the heading level so that Write is under Commands. Write will open a new file to write in our Digital Garden. Since we don't necessarily know what we want to title what we're writing, we'll leave the title as optional and ask the user for it later if they don't provide it upfront.

[2:18] This README describes our first subcommand. We'll have a binary name, Garden, with a subcommand called Write that takes an optional argument called Title.

https://app.egghead.io/api/v1/lessons/rust-readme-driven-planning-for-a-digital-garden-cli-in-rust/transcript

https://app.egghead.io/api/v1/lessons/rust-initialize-a-new-cargo-binary-crate-in-a-new-package/subtitles

Chris Biscardi: [0:00] After sketching out some of our README, we'll want to initiate a new Cargo project. We'll use cargo-init for this. Cargo-init defaults to creating a new binary application. This creates a binary crate inside of our package. You can choose between initializing a binary crate and a library crate when using cargo-init.

[0:23] If we look at the file list, we can see a .gitignore, a src folder with a main.rs in it, and a Cargo.toml. If you're familiar with other ecosystems, such as npm, Cargo.toml will look familiar to you. Instead of a package.json, this file is written in TOML, but it contains the same information, such as the name of our package, the version, the authors, the edition of Rust that we're using, and then we can specify our dependencies, including our dev dependencies.

[0:55] The .gitignore contains a single entry, /target. /target is where all of our code is going to compile into whenever we do a cargo build or a cargo run. The code that we'll compile into our binary is located in src/main.rs. In this case, we have a small program with a single main() function that uses a println!() macro to print "Hello world."

[1:18] If we run cargo run, cargo will call out to rustc to compile our application and run it. In this case, cargo run selects the default binary. It compiles our package, DigitalGarden_v0.1., and my package is located in users/Chris/egghead/DigitalGarden. It'll tell us when it's done, and how long it took, and it'll tell us which version it's running.

[1:43] We compiled a debug release. Inside of target, inside of the debug folder, we'll find a binary called DigitalGarden that prints "Hello world."

https://app.egghead.io/api/v1/lessons/rust-initialize-a-new-cargo-binary-crate-in-a-new-package/transcript

https://app.egghead.io/api/v1/lessons/rust-rename-the-default-cargo-binary-to-be-different-than-the-package-name/subtitles

Chris Biscardi: [0:00] After running cargo run, we can see the path as target/debug/digital_garden. That means the name of our binary is digital_garden, which is the same name as the package. If we bring up in Cargo.toml, we can confirm that.

[0:14] We can change the name of the binary by using a bin field. Note that because Cargo packages can have multiple binaries, this is an array. We'll rename the binary to garden and specify the path as being src/main.rs. We could change the path, but it is conventional to have the default binary be src/main, while the default library is src/lib.

[0:39] Now we could see that we run target/debug/garden when we run cargo run. If we look in target/debug, we can see a binary called digital_garden and a binary called garden. This is because digital_garden is left over from the first build, when the binary was still named digital_garden, while garden is the new binary name.

https://app.egghead.io/api/v1/lessons/rust-rename-the-default-cargo-binary-to-be-different-than-the-package-name/transcript

https://app.egghead.io/api/v1/lessons/rust-using-the-todo-macro-to-typecheck-unwritten-code-that-will-be-implemented-in-the-future/subtitles

Instructor: [0:00] Our main function uses the PrintLlne macro which prints out "Hello World" when we run it. We're going to replace the PrintLine macro with a todo Macro. Now, when we run our application, we'll see that the thread panics. It panics with a specific message, "Not yet implemented."

[0:17] Todo has a very specific benefit over PrintLine in that it will allow us to type check our program without actually completing the implementation. How it does that is out of scope for this lesson, but we do have two other options that we could have used instead, as well.

[0:32] The todo macro itself indicates unfinished code as specified in the documentation. This can be exceptionally useful if you're prototyping, or trying to type check the code without actually implementing the implementation. Unimplemented and panic are two macros that do the same thing as todo. All three of these macros will panic and crash the application.

[0:55] The reason we aren't using panic here is because panic should be used when a program reaches an unrecoverable state. What we have here is not an unrecoverable state, so much as an intent to implement future functionality.

[1:08] For similar reasons, we aren't using unimplemented. Unimplemented just says, "We haven't implemented that code." Whereas using todo indicates some intent to implement that in the future, unimplemented carries no such connotations.

[1:24] That said, if you feel like panic or unimplemented is better for your use case, feel free to use them.

https://app.egghead.io/api/v1/lessons/rust-using-the-todo-macro-to-typecheck-unwritten-code-that-will-be-implemented-in-the-future/transcript

https://app.egghead.io/api/v1/lessons/rust-using-color_eyre-and-distributed-tracing-to-yield-better-error-messages-to-the-user/subtitles

Instructor: [0:00] The todo macro is quite useful and exposes what happens if future functionality in our program panics. This could be more readable and also contain more information while also including more colors. To achieve this, we'll use color-eyre.

[0:19] Color-eyre includes an error report handler that we can attach to our main function that handle things like panics and errors in a more visual way. Since we will have actual human users using our CLI, this will make for a better user experience.

[0:36] If you're used to other package managers with add, remove, and upgrade functionality like npm or Yarn, you'll want to use cargo-edit. By using cargo install cargo-edit, we gain access to the add, remove, and upgrade subcommands. I already have it installed, but you'll see a slightly different output when you install.

[0:56] Now that we have cargo-edit installed, we'll do, cargo add color-eyre. Note that I mistyped the package name with an underscore instead of a dash. This is a fairly common mistake for me to make. I'm happy that cargo-edit handles this for me.

[1:12] If we look at the dependencies in our cargo.toml, we'll see color-eyre specified as .5.10. While we don't have to use color-eyre error result to be able to use it in our type signatures, we'll do it here to make our type signature a little bit shorter and make it easier to use the result type in future functions.

[1:33] If you're less familiar with how use works, note that it's not actually an import, and that writing the full path in the type signature will achieve the same result. We modified our main function to return a result with a value of unit. We aren't allowed to return anything other than unit inside of the result here.

[1:54] For more information about how result works and why it works, you can read question mark in main and tests in the Rust Edition Guide. Note that, like we've said before, we don't actually have to use different exports. We can use the fully qualified path instead.

[2:12] In this case, we'll use the color-eyre install function. On docs.rs, we're going to search for Install. Click the Install function, and see what the return type is. In this case, Install picks no arguments and returns a result of unit and report. This is the same type that we have in our return type of our main function.

[2:36] We can use a question mark to propagate the error back up to our main function if this function fails. Otherwise, we can just continue with our program.

[2:46] Now when we cargo run, we'll see color-eyre getting downloaded. After our program is built and run, we'll see that there's new output. We can see the source location, including the file and the line number. We can see the message that was created from our todo Macro. We can see some of the application panic crash output.

[3:09] As we move forward in building out our CLI, different errors will add additional contexts to these error messages. This will make it such that if a file doesn't exist, for example, we know which file we're looking for and why, as opposed to just saying, "File doesn't exist. Fail."

[3:29] We haven't shown off everything that color-eyre can do here. In addition to panic handling, color-eyre allows us to track additional information in a context of our errors and includes suggestions for what to do, like taking advantage of the distributed tracing infrastructure that the Tokio project has produced. We'll see more of how this helps as we build out the CLI.

https://app.egghead.io/api/v1/lessons/rust-using-color_eyre-and-distributed-tracing-to-yield-better-error-messages-to-the-user/transcript

https://app.egghead.io/api/v1/lessons/rust-setting-up-git-like-subcommands-using-structopt/subtitles

Instructor: [0:00] The StructOpt crate allows us to derive our human person functionality from our Struct definitions. The name is a play on Struct Opt and allows us to derive the StructOpt trait, as well as specify various attributes, which will indicate how to handle various fields in our Struct.

[0:21] We'll add StructOpt to our project using cargo-edit like we did with color-eyre. Note that in our Cargo.toml, StructOpt showed up at version .3.21.

[0:32] Back in our main .rs, we can use structopt::StructOpt, and then we can write our structs. In this case, we have an option struct with a subcommand field called Command. This means this command enum will be what defines our different subcommands. We use an enum here and not a struct because while structs can have multiple fields at the same time, an enum can only have one option at one time.

[1:00] If we had another variant in our enum, say, Search, we could only use Write or Search. We couldn't use both at any given time as a user of the CLI. Our subcommand enum has a single Write variant right now with an argument called title as an optional string.

[1:22] By default, all fields are positional arguments when it comes to deriving StructOpt. That means if we left it as it is right now, the command would work like, garden Write my title. This isn't what we wrote in the read me in the beginning, so we'll choose to change it.

[1:39] In the StructOpt attribute macro on the field level, we can use short and long to both account for -t and --title in our CLI. Note that because we're deriving this, StructOpt will inspect the type of title and know that this is an optional flag. After we install color-eyre, we can let opt = Opt::from_args.

[2:06] From_args is a function placed on the Opt struct by deriving StructOpt on it. We'll also debug using the Debug macro to display any of the arguments that get passed in. This will let us visually debug as we get started and get used to using StructOpt.

[2:25] We can cargo run, and cargo will download and build StructOpt into our binary. Note that when I run cargo run with no arguments, we get help output. That help output also includes subcommands, help, which prints this message, and write, which we haven't documented yet.

[2:45] If we want to call the write subcommand for our binary, we can do, cargo run write. The application crashes, as expected, because we still have todo, but we also get the Debug output. The debug macro gives us a file name, a line number, the name of the argument, and the value it equals.

[3:08] In this case, we have an Opt struct with a command field that contains a write variant with a title of none, because we didn't pass one in. This Debug macro is also why we needed to derive Debug when we derived StructOpt. If we didn't derive Debug, we would get the Opt struct could not be formatted using the Debug formatter.

[3:33] There's a couple lines of help telling us that Debug trait is not implemented for Opt and a suggestion to even derive Debug or manually implement it. It also tells us why that's required. If we put the Debug trait back in the derive call and we call our binary directly, we can see what it'll look like when a user uses it for the first time.

[3:57] When we Path-T because we specified the short flag on the title field in our write variant, we can see that the title field is, some a.title. Some is an Option type, which is what we specified here.

https://app.egghead.io/api/v1/lessons/rust-setting-up-git-like-subcommands-using-structopt/transcript

https://app.egghead.io/api/v1/lessons/rust-documenting-and-writing-helptext-for-structopt-cli-commands-and-flags/subtitles

Instructor: [0:00] If we run our binary with the help flag, we can see some documentation for the help command as well as the fact that our subcommand doesn't have any documentation. Also notice that the name of our binary in the help output is the package name, not the binary name. Let's start by fixing that.

[0:18] We can use the structopt attribute macro with the name argument set to "garden" to change this. Now, when we run help, we'll see "garden" as the output. If we want to write a little bit more about the CLI, we can use /// and see that whatever we write is output below the binary name and above the usage.

[0:39] We can also write documentation on the subcommand level. Here we can see that the documentation takes the first line of our comment and uses it as the short description under the subcommands. If we instead pass help to a subcommand, we can see that the full description is shown and that the binary name now has the right subcommand attached.

[1:04] We can keep doing the same and document our flags as well. Now we see that the t flag, or the title flag, with the right subcommand has the description "Optionally set a title for what you're about to write about."

[1:18] Note that --help and -h in structopt mean different things, and that -h will give us shorter, more compact output, while --h will give us longer output.

https://app.egghead.io/api/v1/lessons/rust-documenting-and-writing-helptext-for-structopt-cli-commands-and-flags/transcript

https://app.egghead.io/api/v1/lessons/rust-integration-testing-cargo-binaries-with-assert_cmd/subtitles

Chris Biscardi: [0:00] Cargo allows us to execute many different kinds of tests, including integration tests, unit tests, benchmark tests and documentation tests. For now, we're just going to talk about integration tests for our CLI. Integration tests live in /tests in your project directory and only have access to the public interface of a crate.

[0:22] To spawn new commands that interact with them, such as the guardian binary defined in our Cargo terminal, we'll use the cert command. We'll add it to our devDependencies because we don't intend to ship this with our project.

[0:34] Now, even though we have no tests currently, we can still run Cargo tests. Note that we've run zero tests, and the test result is OK. We'll create a new file at testsintegration.rs. This is where integration tests live.

[0:52] Although the file name does not matter, the directory name does. To spawn the garden subcommand, we'll use command from the assert_cmd crate. Tests are just like regular functions, except they have this attribute macro on top, letting Cargo know that they are tests.

[1:11] This allows us later to abstract functionality into other functions that don't count as tests. In this case, we'll use a utility from the assert_cmd crate to pull out the garden binary from the Cargo.toml and build it. Now we can unwrap this, but we can also return a result here.

[1:30] Note that after bringing result to this scope and call it err, we can use that result as our return type. We can then continue to use the question mark instead of the unwrap, but at the end of our test we'll have to return one of the result variants, in this case OK, with the value unit, which is what's specified in our type signature.

[1:48] Since we have a mutable command here, we can continue to add arguments like help, and then we can call assert on that command to give us an assert value that then we can use to test against a successful execution of the binary itself and do things like check to make sure that standard error is equal to an empty string. If we cargo test now, everything works.

[2:10] There's another trick we can use if we cargo install cargo-watch. I already have it installed, so you'll see a couple of dependencies installing here. If we cargo watch -x test, Cargo will run our tests and then wait for anything to change.

[2:28] If we add another test, in much the same way that we did the first one, but this time call out to the right subcommand, and pass help to the right subcommand. We can see that two tests have passed.

[2:40] Finally, if we want to test the right subcommand itself, we can take --help off and actually execute the right subcommand. Note that this panics, because we haven't finished the functionality of the right subcommand and that it's still panicking on "not yet implemented."

[2:58] Also note that we don't have to return a result here. If we ignore this test, we can see that test right is ignored. We have two passing tests. We've also seen that we can choose to unwrap, which will panic or return the error, depending on if we want a result type returned or a unit type returned from our function.

https://app.egghead.io/api/v1/lessons/rust-integration-testing-cargo-binaries-with-assert_cmd/transcript

https://app.egghead.io/api/v1/lessons/rust-matching-structopt-commands-and-using-rust-values-after-move/subtitles

Instructor: [0:00] From here, I'm going to use Cargo Watch, which we installed in the last lesson, to run check and then test. To continue the implementation of our CLI, we can match on opt.cmd. That is the StructOpt Command field.

[0:17] Match lets us match the structure of the value that we're matching on. In this case, we can match on the structure of commandWrite, such that whenever the Write variant of the Command enum is used we execute some code. In this case it will be todo, and I'll remove the final todo.

[0:35] Note that we're also destructuring title here, but cargo check gives us an error. We get the error, use of moved value, value used here after move, title. The move occurs because opt has typed Opt. That is the variable name Opt as the type struct of opt, which does not implement the Copy trait.

[0:58] Since we're not using title yet, we can use the placeholder in our pattern to say, "Hey, we're not using this yet. Don't warn us about it." Now, we get a slightly better error. The use of moved value opt.cmd, same move, copy, the value is moved here in dbg opt, and the value is used here after move, in opt.cmd.

[1:25] This is because we passed opt into dbg, and dbg has taken ownership of this value. Because dbg has taken ownership of this value and used it, we can't use it after that. We can fix this by giving dbg a shared reference to opt. A shared reference means that we can access this value later when we want to match on it.

[1:46] What was happening originally, when we didn't have the shared reference, is called move semantics. That is, if we use the variable and we give ownership to the dbg function, or the dbg macro in this case, the variable moves ownership into that function. We don't get it back after it's done.

[2:06] Passing the shared reference in lets us use copy semantics, which means that the ownership won't get moved into this function and that we can still access the variable later.

https://app.egghead.io/api/v1/lessons/rust-matching-structopt-commands-and-using-rust-values-after-move/transcript

https://app.egghead.io/api/v1/lessons/rust-creating-a-library-crate-to-support-a-rust-binary-crate-in-the-same-package/subtitles

Instructor: [0:01] In our subcommand match, we'll add a new function called write to handle our write subcommand. We'll parse it the argument title, and we'll import it from a library called digital garden. Remember to remove the placeholder that we added last lesson.

[0:19] Digital garden doesn't exist, so we get a use of undeclared crate or module digital garden. To create this library, add a new section in Cargo.toml called lib. The name of the lib will be digital_garden, and the path will be at src/lib.rs.

[0:37] Note the difference between the bin declaration and the lib declaration. Bin is an array, whereas lib is not. That's because we can only have one library crate in our package, while we can have as many binaries as we want. In src, we'll create lib.rs with the following contents, mod write, pub use write::write.

[1:04] Now, because I know what we're going to do later and we're going to add more subcommands in different files, we're going to use more of the Rust module system than we would otherwise have to. We could export a public write function from this file and it would work, but instead, we're going to extend this into another file called write.

[1:28] Rust module system is explicit, so when we write, mod write, we're saying that the library, digital garden, which comes from the lib.rs file, has a module called write, such that the path to the module is digital_garden::write. In our case, digital_garden::write corresponds to a file at src/write.rs. We'll create that file now.

[1:56] Back in lib.rs, pub use write::write says that we have a function called write, in the module called write, that we just defined, and that the function will be exposed publicly. People who have the digital_garden library installed will be able to use the write function from the write module as digital_garden::write.

[2:23] If you're used to JavaScript, the closest analog is, export write, from write.js. By using use, we're effectively shortening the import path to the write function.

[2:37] In write.rs, we'll create a function called write with a visibility of public that accepts the title, that has an option of a string, which is the same argument we parsed in earlier, and returns a result, like all the other results in our application.

[2:55] Inside of this function, we'll leave our to do, as we're not done writing this function yet. We can see that our tests are parsing, which means that our write function is being correctly targeted from our binary crate. To drive the point home a little further, there is a path at digital garden, write:write. That would be lib.rs write:write.

[3:27] Because the module path in Rust is explicit and this module is private, while the function is public inside of the current module, we can't reach into write to arbitrarily use functions. We can only use the function that we've publicized at the digital garden level.

https://app.egghead.io/api/v1/lessons/rust-creating-a-library-crate-to-support-a-rust-binary-crate-in-the-same-package/transcript

https://app.egghead.io/api/v1/lessons/rust-adding-support-for-global-flags-that-apply-for-all-subcommands-with-structopt/subtitles

Chris Biscardi: [0:01] Now we have a write function, which is what we're going to use to write files out to disk, but we don't know where to put them yet. We'll start by going back to main.rs and writing a little utility function. The function name is going to be get_all_garden_dir, and it's going to return us a result with a PathBuf. This means if everything succeeds, we get a path buffer, and if it fails, we get an error.

[0:30] We're going to take advantage of the directories crate to get the user directories. If we can find the home directory, we'll join it with .garden to give us the location of the user's default garden, as it will be home_dir/.garden.

[0:47] Since I'm using rust-analyzer, I can use Command-dot on a Mac to bring up this little menu and import std::path::PathBuf. If I scroll up, you can see that I used std::path::PathBuf format.

[1:03] We can't do the same for UserDirs, because the crate isn't installed yet. Let's stop our watch process and run cargo add directory. Then we can start our watch process again. Note that cargo-check was telling us that we might want to use directories::UserDirs, because we are using in our function.

[1:26] We have one more identifier to bring into scope, and that's Err. We can use the rust-analyzer autocomplete to import, and call it Err(err), but that's not actually what we want. We have to go up and text it what we want, let's call it Err(Err(err)), which is a macro. It's a macro for creating new errors. UserDirs::new() returns an option, so we can turn that into a result with ok_or_else.

[1:58] Ok_or_else takes closure, that takes no arguments and allows us to give an error value. This is important because we're adding context to why the UserDirs failed. Not that because we have a result after using ok_or_else. We can use the question mark to early return if there's an error.

[2:23] If we have a valid UserDirs value, we can get the home_dir and then join it with the garden. Ideally, we don't just supply the location of a garden. The user will probably want to specify that themselves. Using StructOpt, we can let them specify as a short or long's leg or an environment variable.

[2:44] If we go back to our readme, we can specify how this should work. Under commands, we'll add a section called setting the garden path.

[2:55] This will allow us to specify the environment variable as a location for garden right, specify a short flag -p, or a long flag, --garden path. Back in our Opt struct, we can tell StructOpt exactly what we want to see. Garden path, it's going to be an optional path buff, because the user can supply it or not. The short version is going to be p, the long version is going to be automatically derived.

[3:28] We're also going to be able to specify it as an environment variable. Note also that we've used a custom parse function, because path buffers are OS strings. OS strings can include characters that aren't valid UTF eight. Back in Main, we can specify the garden path as the result of a match on options garden path, options garden path being an optional type.

[3:52] If we have a path buffer, we're just going to return that path buffer, and that will become our garden path. This means the user specified one. If we match and there's none, then we're going to get the default garden dir. This is a result. We'll wrap this in an additional error context.

[4:11] Wrap error takes the error that happened, and places that as the source of our new error, adding additional context to what went wrong. To use wrap error on a result type, we need to bring in the wrap error trait from air. In Rust, functions that are added via traits aren't accessible unless the trade is in scope.

[4:37] With our tests passing, we'll choose to force an error and get default guard under to see what this looks like. Here we can see what happens if an error occurs and get the full garden dir. We can see garden path was not supplied, which is the context we wrapped our error in, then we can see the original error.

[4:57] While we forced an error here, the error that would normally occur is this could not find home directory, which is the message that would appear in error number one. The user will get the information that the garden path was not supplied, and we also couldn't find the home directory. If both of those occur, then we don't have a place to put the garden and the CLI tool cannot continue.

[5:22] We also have to change the signature of our write function to accept the garden path. We'll add the argument here, which rust-analyzer is correctly telling us doesn't accept two arguments right now, and we'll change write to accept PathBuf as the first argument.

[5:42] Again, we can use the rust-analyzer Command-dot to do the import for us, or we could write it out ourselves. I'm also going to debug the garden path and the title, so we can remove this placeholder.

[5:55] With everything type-checking and our tests passing, we'll run write, and now we can see the Opt struct and which subcommand we used logged out as well as inside of src/write, the garden path, which for me is Users/chris.garden, and the title that was given.

[6:15] We now have a user configurable garden path. If I wanted the garden path to be somewhere else, I could just say so. Note that the garden path will come in as somewhere else.

https://app.egghead.io/api/v1/lessons/rust-adding-support-for-global-flags-that-apply-for-all-subcommands-with-structopt/transcript

https://app.egghead.io/api/v1/lessons/rust-passing-control-to-the-user-s-favorite-editor-such-as-vscode-from-the-cli/subtitles

Chris Biscardi: [0:00] What user experience do we want for the act of writing? At some point, we have to pass controls to the user, and they have to do something to put some writing down on the page. We have a few options, including letting users directly write into the console or giving them a prepared file that they can open and write in.

[0:21] Writing directly into the console doesn't give a user access to their text editor of choice, which means lacking autocomplete, syntax highlighting, snippets and other functionality they might be used to. Creating a file and handing the path back to the user doesn't quite work for us either as that reduces the utility of the garden write command to the equivalent of running touch filename.md.

[0:42] For our use case, we'd ideally like to open the user's preferred editing environment, whatever that happens to be, then wait for them to be done before continuing. Since we're working with a CLI tool, we can safely assume that our users either know how to or are willing to learn how to set environment variables.

[1:00] This means we can use the editor variable to select an editor to use. This is the same way that git commit works. Note that I have my editor set to EmacsClient right now.

[1:11] I won't be using EmacsClient today. I'll be using VS Code, and I'll show you how to set the editor variable in line with the command, in case you don't have one set either. In Rust, there's a query that handles not only editor, but also various fallbacks per platform. We'll take advantage of edit to call out to the user's choice of editor.

[1:36] The quick usage of edit shown in the documentation allows us to call the edit::edit function with a template and then it gives us back the data the user wrote, which we're debugging here. Note that the wrapper tray is not in scope, which is why we're getting an error here.

[1:55] If we set our editor variable in line to code and then cargo run write, we can see that our program exits early while the file is still open. That's because for VS Code we have to use code -w and then we can write some code here.

[2:16] Take note of the file name which is .tmp with a hash on the end, and it's in a completely different location. In this case, it's in a var/folders/hw, a bunch of gobbledygook and then .tmp. If we save this, close the file, it will return control to our program, which we can see was successful. Content from user is exactly what we wrote.

[2:46] We have no idea what this file really is as a user. The only reason we know is because VS Code happened to tell us why it was open. That tempfile is in a location no user would reasonably find it. Ideally, if anything went wrong, the user would be able to take a look at the in progress tempfile they were just working on which should be in an easily discoverable place like the garden path.

[3:10] Above all else, we don't want to lose a user's work. Additionally, the tempfile doesn't have a file extension which means that while it was writing markdown, the user's editor or my editor as VS Code is less likely to recognize it as a markdown file.

[3:27] We want to add .md to the file path because that's typically how editors determine what language highlighting to use and which mode to be in. What we're going to do is drop down to a lower level in the edit API using edit file and builder.

[3:46] Builder allows us to build a temporary file with the suffix of our choice, .md, some random bytes like the random bytes we saw in the file name earlier, a location for the tempfile, which is going to be in the garden path now.

[4:05] Instead of making it just a temporary file that closes out when this function goes away and gets deleted, we can keep it and make it persistent if anything goes wrong. This builder API returns us a mutable file and a file path.

[4:22] To get back the idea of inserting the template into the file for the user to then fill out, we can use write all on file. Note that write all is part of the write trait, so we need to bring that into the scope from standard I/O write.

[4:38] We've also made the template a CONST because it never changes. CONSTS are usually specified in all upper case. The type of this CONST is going to be a slice of U8 of length 2.

[4:53] If you don't know what a slice is, it's not super important right now. Just keep in mind that this is basically an array of len 2. We can use the B on the front of the string here to make it a byte array. Also, note that we have two characters in here which accounts for the len 2.

[5:12] Also, note that we have a couple of results that come in while we're using this builder API, and we've wrapped them in more context at each point that they could fail with WrapErr. Err allows us to keep chaining as long as we have succeeded in the previous call.

[5:30] If we fail here, we will return with an error from this function. If we fail here, we will return with a different error. If we change the string here, say add another couple characters, we can see that the length of the byte array is checked at compiled time.

[5:49] Instead of two elements, right now we have eight. We could change the type to be a len 8. If it's len 8, it will pass and compile. We don't need these extra characters so we going to get rid of them and return to len 2.

[6:08] Now we can use the edit file like before passing in the file path that we just constructed using a builder. This is now a much more specific file path that is in a much more discoverable place for the user. If this fails, again, we return the error using the question mark.

[6:28] Since we already have access to the file, we're going to read that to string. We need a string to put it into, so we'll create immutable contents that is a new string. If we pass a reference to the immutable contents, to the read_to_string function on file, what we end up with is contents filled with the file contents, which we can debug out.

[6:53] Note that we get some nice syntax highlighting as well as some heading highlighting because of the file extension. I even just got auto format on save which inserted that semicolon for me. We can see the file contents being logged out on line 27.

[7:10] Now we've let the user write using whatever editor they want and all the comforts of that editor, and we've also kept the tempfile around meaning that if anything goes wrong, as it just did because we panic, the temporary file lives in our garden where we can easily find it if we need to.

[7:31] This means that the user sees that something happened with the application that we've written. They can go into their garden and look for this tempfile and see if there is any of them laying around the disk, then they can recover them and choose to rename them and keep them if they wish.

https://app.egghead.io/api/v1/lessons/rust-passing-control-to-the-user-s-favorite-editor-such-as-vscode-from-the-cli/transcript

https://app.egghead.io/api/v1/lessons/rust-using-the-option-type-in-rust-to-pick-from-multiple-values-that-might-not-exist/subtitles

Instructor: [0:00] After getting the user's input, we need to figure out a file name to write the file out as. We can either use the title the user passed in, or we can try to use some heuristics to find a title from the Markdown content they just wrote.

[0:13] We can combine the user's title from the CLI arguments, which they may or may not have passed in and is thus an option type, with the logic we use as a heuristic for the Markdown, which will also be an option. We may or may not be able to get an answer out of it.

[0:30] Title is the first optional type. It's the one the user passed in or didn't pass in to the CLI. The or_else function on options will return the original option if it's a sum value or execute the closure to return a different option if it's none.

[0:48] Document title is an option string, as rust-analyzer is telling us here. Either way, we've covered all of the possible scenarios. If the user passes in a title, we get Title. If the user has written content with a heading, we use the internals of this closure to find that heading and return it.

[1:10] If the user does neither of these, Document title will be None, which leaves us to talk about our Markdown heuristic. We can take the contents of the file that we just read to a string and turn it into an iterator over lines.

[1:25] So you don't have to read the Markdown spec, I'll tell you that in the Markdown spec ATX headings have to start with a hashtag, or an octothorpe, followed by at least one space. This is not true for all possible headings that you can put into a Markdown file, but it's true for the primary heading if it's in ATX format. That's what makes this a heuristic.

[1:47] Contents .lines give us an iterator, which we're using .find on, which gives us a line. On each line we test to see if it starts with the hash and a space. If it does, then we use .map to map over that.

[2:04] Find returns us an option. Map will let us operate on the value inside of the sum if there is one. If it's None, this map will never execute. Given a line, we'll want to trim off the starting hash and then the space.

[2:22] We want to match the type of the title, which is a String, so we use ToString because we can see the trim-start matches gives us a string slice. We need to convert that into an owned string, or a String. Let's give it a go.

[2:41] We can see our Options got debugged out. We can start writing a heading, some content, save, exit the file. Our program crashes as expected because we still have to-do at the end. We can see that the file contents are here and the document title is None, but it shouldn't be None. It should be a heading.

[3:05] If we look at the contents of file here, we can notice a bug. When we wrote to the file with write_all using our template, it seeked the internal cursor of the file forward two bytes, which means that when we read to string, we're reading from a two-byte offset into the file because we haven't reset that seek. Thus, we don't get the initial half for our heading.

[3:33] To fix this, we can seek on the file right before we try to read the whole thing. Note that this will require bringing SeekFrom into scope, which will seek us from the start of . We also need to bring in Seek trait, which is what will allow us to use this Seek function on the file.

[3:56] Without bringing in Seek, we won't get the Seek function. Without bringing in SeekFrom, we can't construct this start value. Now we can see that we've seeked for the beginning of the file, we've debugged out the entire contents of the file, and our document title gives us some a heading.

https://app.egghead.io/api/v1/lessons/rust-using-the-option-type-in-rust-to-pick-from-multiple-values-that-might-not-exist/transcript

https://app.egghead.io/api/v1/lessons/rust-prompting-the-user-for-input-with-rprompt-and-loop/subtitles

Chris Biscardi: [0:00] Given the potential document title, we now want to ask the user if the title is still what they want to use so that we can write the file to disk.

[0:09] This will involve two paths, depending on if we have an existing potential option and document title or not. We'll match on document title. If we have an option, we're going to ask the user to confirm the file name.

[0:25] For now, we'll leave that as todo. We'll move on to askForFileName, which is the case where we don't have a document title, which means the user hasn't passed one in and they didn't type enough in the markdown file to let us use our heuristic to find a title.

[0:42] We're going to start with askForFileName as opposed to confirmFileName, because askForFileName will be used inside of the confirmFileName function.

[0:50] We're going to add another package called rprompt. Note that our askForFileName takes no arguments but returns a result of string. We'll use rprompt and specifically prompt_reply_stderr to ask for a file name from the user.

[1:07] Note that this is a two-line query. First line we'll have "Enter file name." The second line, we'll just have an arrow. I've used a backslash to give us a new line so that both of these are on the same horizontal column in our source code.

[1:24] Note that rprompt returns a result so we don't need to do much here, but we do want to add a little bit of context just in case something goes wrong. This again uses the wrap error trait I'm calling error and we say, "Failed to get file name."

[1:41] Next, we'll implement confirmFileName. Again, we create a new function. This time we want to pass in the raw title, which will be a string slice. If we go back up to confirmFileName, we can see that we have a raw title inside of this sum which we've destructured out of.

[1:57] We'll edit as an argument here. Cargo check does tell us there's a problem with this because we've defined our confirmFileName function to take a string slice, but we've passed in a string. We can see the string because Rust analyzer tells us here.

[2:13] Cargo check tells us to consider borrowing here which is what we'll do. We can turn a String into a string slice by borrowing. Inside of confirmFileName, we'll use control flow construct called loop.

[2:30] Loop will infinitely loop until we break. When we break, we're allowed to give it a value to break with which will end up in this case because loop is the only expression here and we haven't included a semicolon. The break value will be result of string.

[2:48] Again, we use a similar pattern with rprompt prompt_reply_stderr. In this case, we'll use the format macro to ask the user if the current title which we pass in using this display formatter is good enough for them by asking, "Do you want a different title?" "Yes or No."

[3:10] We've capitalized N because N is the default value if they just hit Enter. This is the convention. It really isn't enforced anywhere, but it's good enough for us for now. Remember that rprompt prompt_reply_stderr returns us a result so we could wrap that result in an error to give it more context. In this case, we'll let the user know that we failed to get input for a yes or no question.

[3:36] Given the result, we'll match on the result as str. I use as str here because string literals are string slices in Rust. This saves us a little bit of typing because we don't have to do string.from to get a String or an own string.

[3:56] Inside of a match, we can use multiple patterns. In this case, we're checking to see if it is y or Y. If it is, then we'll ask for the file name and break with the result. If it's n, N or the user hasn't given us any input, we'll break with an OK the slugified title value.

[4:22] If neither of those occur, we'll loop through again and ask again. The break syntax might be a little bit confusing if you haven't seen it before. Remember that in Rust, most things are expressions and expressions return values.

[4:38] In this case what we're doing is saying we're going to break out of this loop and return the value that is returned from this function call. The return value of loop becomes the return value of this function, which, because it's the only expression in confirmFileName, also becomes the return value of the entire function. A similar thing is happening down on line 79 where we break with an OK value. OK is a result variant.

[5:06] I also have slug slugifying here which is a package we haven't added yet. The reason we have this is because file names can technically have spaces in them.

[5:15] We're going to slugify our file names like URLs for a few reasons. One is that when starting out, many programmers fail to quote file name arguments in their batch scripts which results in file names with spaces being treated as separate arguments, which can be confusing and hard to diagnose.

[5:33] Since this is a CLI tool, we want to make sure that this as palatable as possible especially to new programmers. Another reason is that this is a digital garden CLI and digital gardens are often stored in git, accessed from multiple different file systems as well as from URLs.

[5:51] While strictly speaking we don't need to slugify our file names especially since most modern systems can handle spaces correctly, we will here so as to adhere to a safer set of characters. We have to add this slug package.

[6:06] In confirmFileName, we've already used it, but in askForFileName, we still have to. Remember map that we used before can be used to map over the value inside of a structure. In this case, we're mapping over a result.

[6:24] If it's OK, then we take the value inside of the OK variant and we slugify it returning the OK variant with a new value inside of it. If it's an error, map won't touch it because map only operates on OK for some values. That is values inside of structures that represent success.

[6:46] The fact that askForFileName and confirmFileName both results Strings is no accident. The match on the document title, the return values for confirmFileName and askForFileName in each branch of the match must have the same type to be valid. If they had different types, this match would fail to compile.

[7:09] We'll add in a debug of contents and file name just to make sure everything works. We can see that if we have a title, we get current title heading here, "Do you want a different title?" If we say no, the program will end so we'll say yes which kicks us into the askForFileName cycle.

[7:31] The program gives us "Enter file name" and the opportunity to enter one. Contents of the file include the heading which is what we pulled up before for the original title. The user however told us that they wanted a different name which is "my awesome file," which we can see here. This is how we can interact with the user for quick back and forth.

https://app.egghead.io/api/v1/lessons/rust-prompting-the-user-for-input-with-rprompt-and-loop/transcript

https://app.egghead.io/api/v1/lessons/rust-checking-for-file-existence-with-pathbuf-to-ensure-unique-filenames/subtitles

Chris Biscardi: [0:01] The next thing we want to do is take the filename, which we can see rust-analyzer is treating as a result string report, which isn't what we want. If there's an error here, we want that error to propagate back through the function, so we use a question mark to do that.

[0:19] Then we're going to write a loop. We used a loop already, so I won't explain too much about that. We're using this loop to format a new file name that is unique. We need to do this because, if there's a file with the same name as the user wants, we don't want to overwrite that file.

[0:38] The approach we're going to take is, if we have a file named hello.md that already exists and the user wants to write out hello.md again, we're going to give them hello1.md, which preserves both files. We can start out with the number . This is going to be a mutable variable because it will increment until we hit a number that gives us a unique file name.

[1:04] We'll use format again with two display formatters. One will be the file name that we got from the user. The other one will be a number. In the case of , we won't add anything to the file name. We'll make this an empty string.

[1:18] In the case of it being greater than , we want to add the number, so we'll stringify the number then put it into the format. This gives us a destination file name of hello1. We're going to finish off the rest of the file name by joining the garden path to the destination file name. This gives us a mutable path buffer on which we can set the extension of this file.

[1:43] At this point in the code, what we have is a path to the garden path and a file of hello1.md. Path buffers include a function called exists that allows us to detect if this file already exists.

[1:59] If we have hello.md here, test that exists will return true and we'll increment i and loop back through again trying with hello1. If it doesn't exist, that means we can take the temp file that we had before and rename it into the official location in the garden path.

[2:20] Note that we have to import fs which is from std::fs. Rust-analyzer helps us out a little bit, but we're getting used here after move, when we try to use the filepath on line 65. This is because all the way back up here, when we got the filepath from the builder, we passed it edit_file.

[2:41] These are the same semantics that we came across earlier in this course which are called move semantics. Move semantics are the default in Rust. In this case, we're moving filepath into this edit_file function.

[2:54] To use copy semantics instead, we can pass a reference into edit_file and if we save, we can see that later on, we can use the filepath in our rename function. Our code checks and the test passed, so let's give it a whirl.

[3:12] Also note that we're returning OK(unit) if everything that we've written succeeds. We'll run our write command with VS Code. We'll give it some title and some content. We'll save and exit the file, which returns control to our program. The current title is "Some Title," and that's going to be OK for me this time, so I'll hit Enter.

[3:35] If we look in our garden, we should see a file with some title with the content, a heading of "Some Title" and on line 3, some content. This is, in fact, what we see. Our program has succeeded. Let's review what we've done so far.

[3:52] In main.rs, we've installed color_eyre to give better error messages. We get the options using structopt from_args, and then we debug that out. We no longer need this debug, so we'll remove it. If the user passes in a garden path, we'll use that. If not, we'll get a default garden path. If anything fails, we'll wrap the error with additional context for the user.

[4:18] Finally, we'll match an Opt command and use destructuring to pass the garden path and the title into our write function. Our write function lives in a file called write.rs which we're re-exporting from lib.rs. We use a builder to build up the file with the appropriate extension and a couple of other configurations.

[4:43] We write out a constant to the file as a template so when the user opens a file, they have something to work with. We pass the control to the user using a filepath we just created. When they're done editing the file in their editor of choice, we make sure to [inaudible] back to the beginning of the file and read it into a string.

[5:04] Given the fact that our user can choose to pass in a title or not, we combine multiple options together and try to find a title that we can use. If we do find one using either our heuristic or from the user, we ask the user to confirm at this point because they've been writing for a while, and maybe they change their mind about what they're writing about. If we can't find one and they didn't pass one in, we ask them for one.

[5:29] Finally, once we have a file name and the contents of the file, we find the unique file name that we can write out to disk without conflicting with other files, finally renaming our temporary file in the garden path to an actual file in the garden path.

https://app.egghead.io/api/v1/lessons/rust-checking-for-file-existence-with-pathbuf-to-ensure-unique-filenames/transcript

https://app.egghead.io/api/v1/lessons/rust-using-owo_colors-extension-traits-to-colorize-terminal-output/subtitles

Instructor: [0:00] We have two functions for interacting with the user and printing lines to terminal asking for input. Let's make this nicer to use by adding colors, so that the user can differentiate between different pieces of the input. We can do this by bringing in extension trait for formatting into Scope called OwoColorize.

[0:22] In this case, color-eyre re-exports it, so we can pull it in from there. It's also its own package if you want to use this in other projects. Extension traits are one-off traits that are used to add functions to a type that our create doesn't own.

[0:38] A create can create the new trait and implement the functions defined by that trait on a type that create doesn't own. If we bring that trait into Scope, like we just did, the type will get the extra functions. In this case, OwoColorize is used for adding color functions to formatters like display and debug.

[1:01] We'll start with ask for file name. To access the extension trait functions we need to use a format. Now that we've introduced the format macro, we'll add a Display formatter.

[1:18] This means that the string that we're passing in here will be formatted with the Display trait in this string here. This allows us to use the extension traits on this string, which we can then do to make it blue and bold.

[1:37] Confirm file name will do a very similar thing, making two display formatters and some additional text where we're asking for user input. We'll pull out current title and make it green and bold.

[1:56] With cargo checking and all of our tests passing, we'll now take it for a spin. We can see that the current title is now green and it says, Some heading. Do we want a different title? Yes, we do because we want to see the other input, which we can see is now blue and also bold.

[2:14] This gives user input a different color than the program output, helping to differentiate the user's own input from what the program is asking them to do.

https://app.egghead.io/api/v1/lessons/rust-using-owo_colors-extension-traits-to-colorize-terminal-output/transcript

https://app.egghead.io/api/v1/lessons/rust-using-assert_fs-and-predicates-to-integration-test-with-a-real-temporary-file-system/subtitles

Instructor: [0:01] If we go back to our integration desk, we'll remember that two of them are passing, and we ignored one early on that was meant to test whether the right command actually worked. We're going to write this test now.

[0:14] We can get rid of ignore, and we'll see it fail on the right. In this case, the failure mode is that it just waits for user input forever which is unfortunate. We'll kill the watch process so that doesn't happen anymore. We'll test manually for the moment.

[0:37] The first thing we want to do is create a fake editor script. We'll call it fake-editor.sh. What this is, is the program that we're going to execute as the editor.

[0:51] In our command line usage, whenever we test it manually, we've been using EDITOR="code -w". This program is going to be that editor. In this case, all it's going to do is echo testing to whatever file name it gets. These two arrows mean that it will concatenate to whatever is already in the file, which means that our template is preserved as well.

[1:19] Then, we'll write our test using assert_cmd to build up a Command that points to the garden binary in our Cargo.toml. We'll get rid of assert for the moment and add in a way to get the fake editor path script. In this case, we can use the current_dir. We'll expect that we can get the current_dir because this returns a result. If we can't, this test will fail.

[1:48] We'll join tests because current_dir is the root of our package. We'll join with fake-editor.sh. This gives us a path buffer, which we can use to check to see if the file exists. This gives us an early indication about whether we got the path or the fake editor script correct or not. If it's not correct, we'll panic and say, "Hey, you know, we couldn't find the fake editor script."

[2:16] Additionally, we'll take the mutable command that we have, which is calling our garden bin. We'll add the editor environment variable with the fake_editor_path. We turn the fake_editor_path.into_os_string and place it into the environment. Then, we add an argument of write, a -t for the title flag, and an argument, atitle. This is the same as writing -t atitle on our command line.

[2:48] Because we already have a title, the only thing that we'll need to do here is write the standard N\n and an Enter key which is a new line here, .write_stdin takes bytes, so we'll turn our string slice into bytes. That will respond to our prompt for us when it asks us for input saying, "No, this title is OK." We used .assert() to give us the assert so that we can say, "Hey, this binary exited successfully."

[3:21] Now, if we cargo test, we'll see something unfortunate. This is not a good error message for what's going on.

[3:33] Because I know the internals of the libraries that we've used, I know that nano is one of the default platform choices for macOS for the edit package that we used earlier. That means it's failing to use our fake editor script.

[3:47] In this case, it's because our fake editor shell script doesn't have executable permissions, which we can give it with a chmod +x and then a path to the fake editor script. Now, when we test, we can see that the test passes.

[4:04] We do have a problem here, though, that if we look in our garden for atitle.md, for some reason, it's there. No matter how many times we run this test, we'll keep getting more and more atitles with increasing numbers. You can see that this first atitle doesn't have any content, which is the one that didn't work, whereas atitle 5 is a successful test.

[4:32] There's a couple of problems here. One is that we're making our default garden directory pretty dirty, just by running a couple of tests. We don't want to do that because we don't want to mess with it. We want to be able to run our tests on the same system that we're using the CLion.

[4:49] The other problem here is that we're not testing for the file existence, so we don't know if this file's successfully got written out. All we know from this test is that the command did an error when it ran. We can solve this with assert_fs and predicates.

[5:08] Assert_fs will let us create fake files and fake directories that we can run our test in while interacting with a real file system. Predicates will help us to test if the files that we expect to exist actually do exist or not.

[5:22] Change your test to use a temporary directory somewhere on our file system. We need to use a assert_fs::TempDir::new which will give us the temp_dir. Then, we also need to add the environment variable for the GARDEN_PATH to point to that temp_dir, which we can do with temp_dir.path().

[5:44] Finally, we want to use temp_dir.child() with the file name that we were looking for to look for this file name inside of the temporary directory. We don't know where this temporary directory is, so we have to access this using .child() of the temp_dir. We can also assert that the path exists using the predicate from the predicates crate.

[6:07] Note that for these, to both work, we have to bring in the preludes. A prelude is an import from a library that the library author thinks is going to be useful to have in scope all the time.

[6:20] Both of these preludes include a bunch of functions and other traits, and things like that, that the library authors think you'll want when you write tests with these libraries. The star means that we're importing the entire prelude, which is all of the exports.

[6:36] Now, when we run cargo test, we'll download the packages and we can see that our tests pass. If we look into our garden now, before we run the tests, we can see there's no atitle files. If we look after we run the tests, we can see that there's also no atitle files, which means that we're successfully using the temporary directory to write our files into.

https://app.egghead.io/api/v1/lessons/rust-using-assert_fs-and-predicates-to-integration-test-with-a-real-temporary-file-system/transcript

https://app.egghead.io/api/v1/lessons/rust-abstracting-test-utilities-inside-integration-test-files/subtitles

Instructor: [0:00] While we have TestWrite, which tests our application's write subcommand with a given title flag, we can also set up additional tests, such as for using a written title in the document for the file name instead of passing one on the command line.

[0:13] I'm going to copy and paste this entire test and name one TestWrite With Title and name the other TestWrite With Written Title. Both of these tests currently pass, because they're exactly the same code.

[0:27] Let's start by fixing the second test and removing the title flag. This will cause our application to write out a file called testing.md, which is the content of the heading in the file. As a reminder, our fake editor echoes testing to the end of the file, which will result in # testing. We can see that our test is panicking and that we have failed the exists test on the file.

[0:54] In this case, we can rename it to testing.md, and all four of our tests are passing again. This still leaves us with a lot of duplication between these two tests. That's a lot of room for user error. It's also a lot of room for refactoring pain if later we want to change anything about how these slides are handled, or how this fake editor path is going to be inserted.

[1:16] Let's abstract the creation of the temporary directory on line 27, the fake editor script path on line 30, and the command itself on 29, into a utility function. We'll have a function called set-up command that will return a command in a tempter.

[1:34] The port is relatively straightforward. By that what I mean is that we haven't made structural changes to the functionality of any of this code. We still create the tempter. We still create the command. We're getting the fake editor path in the same way.

[1:49] We're checking if it exists. The only real change here is that we've cut off the environment variable definitions from being in our task to being in our helper. That means our editor and garden path will get inserted by this helper instead of by our test itself.

[2:08] To return multiple values for our arrest function, we have to return a tuple. We could also set up a struct, but this return value doesn't deserve a name. We're only using it as a helper. We're going to use a tuple which allows us to put two different type values in the first and second slots.

[2:28] Now, if we use our setup command instead of a bunch of the code that we had there before and we also have removed the environment variable declarations from our SAR, we can still chain our arguments on chain our standard in, and assert on the output.

[2:42] We'll do the same for the other test, again removing the environment variable declarations. That's it. Now we have a helper that we can use to create any number of tests beyond this.

[2:53] As a final note, I'll say that this setup command isn't run as a test itself, because it doesn't have the test attribute like we have on line 25 here. Line five has no attribute, so this is not recognized as a test.

https://app.egghead.io/api/v1/lessons/rust-abstracting-test-utilities-inside-integration-test-files/transcript

Creating a Digital Garden CLI with Rust

Chris Biscardi

What you'll learn:

You might also like these resources:

Write Your First Program with the Rust Language

Learning Rust by Working Through the Rustlings Exercises

Basic Types in Rust

Credits

Course Content

You might also like these resources:

Write Your First Program with the Rust Language

Learning Rust by Working Through the Rustlings Exercises

Basic Types in Rust