Forem: Sean Larkin

One Crate a Day: has-flag

Sean Larkin — Tue, 24 Jan 2023 18:13:58 +0000

Welcome to "One Crate a Day", my daily journal as I dive into the world of Rust programming. As a JavaScript developer with a background in open-source, I've decided to take on the challenge of re-writing popular JavaScript packages for the Rust community.

Here are a few tl;dr goals I have for this project:

👨‍🎓Learn Rust & Popular JavaScript modules
📦Contribute to the Rust community by publishing new Crates
👨‍🏫Share my learnings, tips, and best practices with you

If you've come here to learn how to install, start Rust from scratch, or setup the toolchain for your IDE/environment, see the Rust Handbook! Otherwise, lets dive in!

Crate #1: `has-env-flag`

Original Package: sindresorhus/has-flag

Sindre's JavaScript packages exemplify the concepts of single purpose and reusability. Often times only implemented as a single exported function. has-flag is no different in this regard.

Review

This single function module allows developers to quickly detect the presence of a specific flag in the argv (arguments passed to the script/binary that was run). The code for the module is as follows:

import process from 'process'; // eslint-disable-line node/prefer-global/process

export default function hasFlag(flag, argv = process.argv) {
  const prefix = flag.startsWith('-') ? '' : (flag.length === 1 ? '-' : '--');
  const position = argv.indexOf(prefix + flag);
  const terminatorPosition = argv.indexOf('--');
  return position !== -1 && (terminatorPosition === -1 || position < terminatorPosition);
}

With this module, we can easily check for the presence of a specific argument ("flag") based on what was passed into our script. Here's an example from the README:

// foo.js
import hasFlag from 'has-flag';

hasFlag('unicorn');
//=> true

hasFlag('--unicorn');
//=> true

hasFlag('f');
//=> true

hasFlag('-f');
//=> true

hasFlag('foo=bar');
//=> true

hasFlag('foo');
//=> false

hasFlag('rainbow');
//=> false

$ node foo.js -f --unicorn --foo=bar -- --rainbow

Approach

To start my journey, I decided to craft my unit tests first. This way, I could work backwards until I had my solution.

Learning #1: Cargo uses Conventions

Cargo, which is the out-of-the-box tool for running tests, installing packages/dependencies, and more, has conventions for building libraries versus binaries.

By default, Cargo looks for one of two conventions in the workspace:

Libraries: If you are building a Rust library ("Crate"), Cargo will enforce the presence of src/lib.rs in your workspace.
Binaries: If you are building a Rust binary, Cargo will enforce the presence of src/main.rs.

I love this! Every time I crack open a Rust project, I know exactly where to start/begin reading code.

Learning #2: How to write tests

Next, I learned how to write tests in Rust. From all of the packages I've looked at, and according to the Rust Handbook, unit tests are written in the same file! Additionally, you'll see the usage of Macros heavily in Rust tests. Macros are a powerful tool for creating code expansion at compile time, saving you from writing lines of boilerplate code.

Take the following test I wrote in my module as an example:

// Macro for setting up a test module
#[cfg(test)]
mod tests {
    // Gives access to outer scope (not just the `pub fn`'s)
    // great to test functions used in Dependency Injection
    use super::*;

    // Macro that turns a function into a unit test
    #[test]
    fn args_with_value_not_matching_double_dash() {
        let args = vec!["--foo", "--unicorn=rainbow", "--bar"];
        let expected_value = "unicorn=rainbow";

        assert!(_has_flag(
            args.into_iter().map(ToString::to_string),
            expected_value
        ))
    }
}

#[cfg(test)] macro: This is our macro for setting up our test module. It instructs Rust to compile and run the test code only when you run cargo test
#[test] macro: This macro converts the function into a unit test! You will use macros like assert!() or assert_eq!() to validate the results of the code you want to test.
use super::*: Exposes the outer scope to your inner test module. The glob allows anything defined in the outer scope to be used in your test functions (anything not defined with pub fn)!

Learning 3: Working with `std::env`

After implementing the tests I decided to take a crack at writing this module. Much thanks to Steve Klabnik, who helped me with getting the types for the function and setting up dependency injection, this was the first iteration:

pub fn has_flag(flag: &str) -> bool {
    _has_flag(std::env::args(), flag)
}

fn _has_flag<I: Iterator<Item = String>>(mut args: I, flag: &str) -> bool {
    let prefix = if flag.starts_with('-') {
        ""
    } else {
        if flag.len() == 1 {
            "-"
        } else {
            "--"
        }
    };

    let position = args.position(|arg| arg == format!("{}{}", prefix, flag));
    let terminator_position = args.position(|arg| arg == "--");
    position.is_some() && (!terminator_position.is_some() || position < terminator_position)
}

std::env::args(): This is how you can access argv or arguments that the program was started with. std is the Rust standard library and is available to all Rust crates by default.
.position(): Searches for an element in an iterator, and returns its index. I saw this as comparable to .indexOf in JavaScript. However I made some mistakes in my code using this and I'll explain why.
.is_some() & is_none(): There is no concept of null in Rust. Rather, Option is a type which is meant to handle the no value being returned. In a few parts of our code, we don't really care what the index is, rather if the index exists. .is_some() is the perfect usage for that here.

Learning 4: Mutability and Bugs!

This code that I initially committed and published actually had a few bugs! However, my initial tests were passing. I had created a GitHub Issue to come back when I had time and implement all of the tests from has-flag's test suite.

My PR introducing the full tests was failing so I knew there must be a bug in the code itself. After getting some feedback from the "Beginners" channel on The Rust Programming Language Discord, I started to realize some of the mistakes I had made. Here is the updated code which passed tests:

pub fn has_flag(flag: &str) -> bool {
    _has_flag(std::env::args(), flag)
}

fn _has_flag<I: Iterator<Item = String>>(args: I, flag: &str) -> bool {
    let prefix = if flag.starts_with('-') {
        ""
    } else if flag.len() == 1 {
        "-"
    } else {
        "--"
    };

    let formatted_flag = format!("{}{}", prefix, flag);
    args.take_while(|arg| arg != "--")
        .any(|arg| arg == formatted_flag)
}

mut args => args: The first code smell I should have noticed when I wrote my first iteration, was that the Rust compiler was forcing me to add mut next to my args parameter for the function. This didn't make sense to me because mut is only needed if I am mutating args.
.position() mutates: This led me to noticing that .position() was not the function I wanted to use. .position() consumes items in the iterator until the predicate is matched. So the code determining terminator_position was actually accessing a mutated args. All my tests involving the -- args terminator were failing as a result!
.take_while(): Takes an iterator, and runs through it until the predicate is true, and then returns an iterator of those items up until the predicate. I think of this similar to an iterator filter. This was perfect for us to use here because we don't want to match args passed after the -- terminator. It also massively simplified our code!

Ship it🎉

This iteration passed all of our tests and I was able to happily merge and publish a new release of has-env-flag. As I continue to work on this journal, I will encounter many new challenges and learnings about Rust, and I can't wait to share them with you.

Resources

Split a commit into 2 commits with `git rebase`

Sean Larkin — Mon, 05 Dec 2022 18:31:40 +0000

Overview

Git is a powerful version control system that allows developers to track and manage changes to their code. One of the key features of Git is the ability to use interactive rebasing to modify the history of a branch.

Interactive rebasing allows you to edit, reorder, and split commits in a branch. This can be useful when you need to clean up your branch history, or when you want to split a commit that contains changes for multiple files into separate commits.

pnpm, yarn, npm lockfiles

Have you ever had to git rebase in your project but consistently had merge conflicts in your pnpm/yarn/npm lockfiles? You may have heard the advice to 'always commit your lockfile in an isolated commit'.

This is because you can use the drop command in an interactive rebase to remove the commit so you can regenerate the lockfile after your rebase.

Often times, I forget this and sometimes I end up with multiple files (including my lockfile) inside my single commit and now I cannot drop it.

Getting Started

In this tutorial, we will show you how to split a commit during an interactive git rebase. We will use a simple example to illustrate the steps involved in splitting a commit.

To begin, let's assume that you have a branch called feature-branch that is based on the master branch. The feature-branch contains three commits, X, Y, and Z, as shown below:

          A - B - C - D [master]
         /
    X - Y - Z [feature-branch]

The Y commit in the feature-branch contains changes for both fileA and fileB. However, you want to split this commit into two separate commits, one for fileA and one for fileB.

Using `git rebase -i`

To do this, you need to start an interactive rebase using the git rebase -i command. In this example, we will use the master branch as the base branch, so the command would be git rebase -i master.

This will open an editor where you can specify the actions that you want to perform on each commit in the feature-branch. In this case, you want to split the Y commit, so you need to replace the pick command for commit Y with the edit command.

Once you save and close the editor, the rebase will start and it will stop at the Y commit. This will allow you to make changes to the Y commit.

Split the Commit!

To split the Y commit, you first need to unstage the changes from the commit. This can be done using the git reset HEAD~ command. This will leave the changes in your working directory, but they will not be staged.

Next, you can use the git add command to stage only the changes for fileA. Then, you can use the git commit command to create a new commit with the changes for fileA. This will create a new commit, Z, in the feature-branch, as shown below:

          A - B - C - D [master]
         /
    X - Y - Z [feature-branch]

Now, you can use the git add command to stage the remaining changes for fileB. Then, you can use the git commit command to create a new commit with the changes for fileB. This will create a new commit, W, in the feature-branch, as shown below:

          A - B - C - D [master]
         /
    X - Y - Z - W [feature-branch]

Tada!

Finally, you can use the git rebase --continue command to continue the interactive rebase. This will apply the changes that you made to the Y commit and create a new branch history with the two separate commits for fileA and fileB respectively!

Now anytime you have a pesky lockfile change included with other files in a commit, you can separate it out, and then drop them during your rebases to make interactive rebase efficient and clean!

I maintain webpack, ask me anything!

Sean Larkin — Wed, 11 Oct 2017 16:47:06 +0000

I'm Sean,

I maintain webpack.

I work on Microsoft Edge DevTools.

I love ðŸ”s.

Ask.

Me.

Anything.

:-D