Project: a task CLI

Lesson 0003 · spec-driven · no walkthrough · 1–3 hours

You asked for a specification instead of a guided build. This is that. There are no numbered stages here and no code to copy. You get four things: a plain-language description of the program, a contract the code must satisfy, a test suite that checks it, and a syntax crib written in a different domain so it shows you the shape without handing you the answer.

Target: packages, structs, and enums — the three you named. Modules & Paths was 0/1 on your diagnostic, so this project is deliberately split across four files that must see each other.

What you are building, in words

A command-line to-do list. You run it with a command and some arguments, it does one thing, prints one line, and exits. It holds tasks in memory for the duration of a single run — there is no file, no database, no interactive prompt, and no loop. One run, one command, done.

A task is four pieces of information:

• an id — a number the program assigns, so you can refer to the task later
• a title — the text you typed, e.g. "buy milk"
• a status — where it is up to: not started, being worked on, or finished
• a priority — how important: low, medium, or high

Read that list again with 0004 in mind, because it is telling you the types. A task is an id and a title and a status and a priority — four things at once, so it is a struct. A status is not-started or in-progress or done — one of three, so it is an enum. Priority likewise. That is the whole modelling decision, and it is why this project targets the topics it does.

The program supports four commands:

Anything else — a command that does not exist, a missing argument, an id that is not a number, an id with no matching task — prints an error to stderr and exits with status 1.

Four commands, each needing different information: add needs a title and a priority, done and remove need an id, list needs nothing at all. That is an enum whose variants carry different data — the Part 2 idea from 0004, applied. Once the user's input is a Command value, every impossible combination is gone: there is no way to hold a done with no id, or an add with an id and no title.

The work splits into three jobs, which is where the four files come from:

1. Describing a task — the types and their small helpers. This is task.rs. It knows nothing about command lines.
2. Understanding what the user typed — turning a list of strings into one of four commands, or into an error explaining why not. This is command.rs. It knows nothing about storage.
3. Holding the tasks and changing them — the list, the id counter, add/complete/remove/find. This is store.rs. It knows nothing about command lines either.

Then main.rs is the thin layer that connects them: read the arguments, ask command.rs what they mean, tell store.rs to do it, print the result or the error. It contains no logic of its own worth testing — which is exactly why the tests can live entirely against the other three.

That separation is the real subject of this project. Each of the three has one job, does not know about the others' jobs, and can be tested on its own. It is the same shape as a backend service: request parsing, domain types, storage, and a thin handler wiring them together.

What it looks like when it runs

$ cargo run -- add "buy milk"
added task 1

$ cargo run -- add "ship the feature" high
added task 2

$ cargo run -- list
1 [todo] buy milk (medium)
2 [todo] ship the feature (high)

$ cargo run -- done 1
completed 1

$ cargo run -- remove 9
error: no task with id 9        # and exits with status 1

$ cargo run -- fly
error: unknown command: fly     # and exits with status 1

Tasks live in memory only. Each run starts empty — persistence is a stretch goal, not part of the spec.

Setup

cd ~/learn-rust
cargo new tasks --lib
cd tasks
mkdir tests
cp ../lessons/0003-tasks-spec.rs tests/spec.rs
cargo test          # 3 unresolved-import errors. Good. Start here.

That first failure is the right one to see:

error[E0432]: unresolved import `tasks::command`
error[E0432]: unresolved import `tasks::store`
error[E0432]: unresolved import `tasks::task`

The tests are asking for three modules that do not exist yet. Your first job is to make those three names resolve — empty files and one line each in lib.rs is enough to change the error.

The package must be named tasks — the tests import it by that name.

Required file layout

tasks/
├── Cargo.toml
├── src/
│   ├── lib.rs        ← library crate root: declares the modules
│   ├── task.rs       ← Task struct, Status enum, Priority enum
│   ├── command.rs    ← Command enum + parsing
│   ├── store.rs      ← Store struct, owns the task list
│   └── main.rs       ← binary crate: args in, text out, exit codes
└── tests/
    └── spec.rs       ← the tests (do not edit)

This layout is the point of the exercise, so here is why rather than how:

cargo new tasks --lib gives you src/lib.rs and no src/main.rs. You create main.rs yourself. You do not add anything to Cargo.toml — no [lib], no [[bin]]. Cargo finds both by filename convention.

You now have one package containing two crates:

• src/lib.rs → a library crate named tasks. All the logic lives here.
• src/main.rs → a binary crate. It is a consumer of the library, exactly like an outside user.

So main.rs reaches your code the same way the tests do — use tasks::store::Store; — not with crate::. Inside the library, modules refer to each other with crate::. Getting this wrong is the most common stumble in this project; when a path will not resolve, first ask which crate am I in right now?

Integration tests in tests/ can only reach pub items through the library crate. That is what makes the visibility rules bite for real, instead of in theory.

Book: 7.1 Packages and Crates · 7.5 Separating Modules into Different Files · 11.3 Test Organization

The contract

These signatures are fixed — the tests call exactly these. Everything else is yours: field order, private helpers, how you search a Vec, how you word error messages.

task.rs

pub enum Status   { Todo, InProgress, Done }
pub enum Priority { Low, Medium, High }

pub struct Task {
    pub id: u32,
    pub title: String,
    pub status: Status,
    pub priority: Priority,
}

impl Status   { pub fn label(&self) -> &str }
impl Priority { pub fn label(&self) -> &str }
impl Priority { pub fn parse(text: &str) -> Option<Priority> }
impl Task     { pub fn new(id: u32, title: &str, priority: Priority) -> Task }

• label returns "todo", "in-progress", "done", "low", "medium", "high".
• Priority::parse accepts exactly "low", "medium", "high". Anything else is None. Note it returns Option, not Result — there is no reason to report beyond "that is not a priority".
• Task::new always starts a task at Status::Todo.
• InProgress is never produced by any command. Define it anyway — it is there so your match arms have a third case to handle.

command.rs

pub enum Command {
    Add { title: String, priority: Priority },
    List,
    Done { id: u32 },
    Remove { id: u32 },
}

impl Command {
    pub fn parse(args: &[String]) -> Result<Command, String>
}

parse receives arguments with the program name already removed. The error type is String — a real project would define an error enum, but that needs traits, so not today.

The last row needs no special handling. Think about why before you write anything for it.

Titles are a single argument. add buy milk without quotes is not your problem — the shell splits it, and "milk" is simply not a priority word, so it is an error. That is acceptable behaviour.

store.rs

pub struct Store { /* private fields — your choice */ }

impl Store {
    pub fn new() -> Store
    pub fn add(&mut self, title: &str, priority: Priority) -> u32   // -> new id
    pub fn complete(&mut self, id: u32) -> Result<(), String>
    pub fn remove(&mut self, id: u32) -> Result<(), String>
    pub fn tasks(&self) -> &[Task]
    pub fn find(&self, id: u32) -> Option<&Task>
}

Rules the tests enforce:

• Ids start at 1 and increase by one on every add.
• Ids are never reused, even after a removal. Add, remove, add again → the second id must differ. This decides how you store the counter.
• tasks() returns them in insertion order.
• complete and remove on an unknown id return Err. The message is yours; the tests only check is_err().

Store's fields must be private. Note that pub struct does not make fields public — each field needs its own pub, and here you want none of them. Everything outside goes through the methods. This is why tasks() exists and why it hands back &[Task] rather than the Vec itself: callers may read the list, and cannot touch your id counter or reorder anything. Encapsulation, enforced by the compiler.

main.rs

Not covered by the tests — this part is yours to judge. It must:

• Collect arguments and hand everything after the program name to Command::parse.
• match the resulting Command and call the right Store method.
• Print the success text to stdout, matching the session at the top of this page.
• Print error: ... to stderr and exit with status 1 on any failure.

Since state is in memory, list after a fresh add shows only that run. That is expected. Seed a task or two in main if you want list to show something.

Derives you will need

The tests use assert_eq! on your types and print them on failure. That requires two abilities you met in our Debug vs Display discussion:

#[derive(Debug, PartialEq)]

PartialEq gives ==. Debug gives {:?} for the failure output. Add Clone and Copy where it makes life easier — think about which of these types are small enough to copy, and which own heap data and therefore cannot be Copy.

If you forget these, the compiler tells you exactly which trait is missing on which type. That error is the lesson; read it rather than pattern-matching against this paragraph.

Syntax crib

A vending machine, not a task list. Same shapes, different domain — you cannot paste any of this.

Modules across files

// src/lib.rs — the library crate root
pub mod coin;
pub mod machine;

// src/coin.rs
pub enum Coin { Nickel, Dime }

// src/machine.rs — one module reaching another, inside the same crate
use crate::coin::Coin;

// src/main.rs — a DIFFERENT crate, so use the package name
use vending::machine::Machine;

Enum with unit variants, and a method that matches on itself

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Coin { Nickel, Dime, Quarter }

impl Coin {
    pub fn value(&self) -> u32 {
        match self {
            Coin::Nickel => 5,
            Coin::Dime => 10,
            Coin::Quarter => 25,
        }
    }

    pub fn parse(text: &str) -> Option<Coin> {
        match text {
            "nickel" => Some(Coin::Nickel),
            "dime" => Some(Coin::Dime),
            _ => None,
        }
    }
}

Enum whose variants carry data, and matching it apart

#[derive(Debug, PartialEq)]
pub enum Event {
    Insert { coin: Coin, count: u32 },   // named fields
    Select { slot: u32 },
    Refund,                              // no data
}

// building one
let event = Event::Insert { coin: Coin::Dime, count: 2 };

// taking one apart — the names bind as variables
match event {
    Event::Insert { coin, count } => println!("{count} x {}", coin.value()),
    Event::Select { slot } => println!("slot {slot}"),
    Event::Refund => println!("refunding"),
}

Struct with private fields, and its impl block

pub struct Machine {
    credit: u32,          // private: no `pub`
    coins: Vec<Coin>,
}

impl Machine {
    pub fn new() -> Machine {    // associated fn: no self, called Machine::new()
        Machine { credit: 0, coins: Vec::new() }
    }

    pub fn insert(&mut self, coin: Coin) -> u32 {   // &mut self: may change it
        self.credit += coin.value();
        self.coins.push(coin);
        self.credit
    }

    pub fn credit(&self) -> u32 { self.credit }     // &self: read only

    pub fn coins(&self) -> &[Coin] { &self.coins } // borrowed view, not the Vec
}

Reading optional arguments

let words: Vec<String> = std::env::args().collect();

words.first()          // Option<&String> — the first, if any
words.get(2)           // Option<&String> — index 2, if any
&words[1..]            // slice of everything after the first

// Option -> Result, so ? can carry it
let name = words.first().ok_or("nothing to do")?;

// match on a &String needs &str
match name.as_str() {
    "insert" => { }
    other => return Err(format!("unknown: {other}")),
}

Turning a parse failure into your own error type

// parse gives Result<u32, ParseIntError>; map_err rewrites the error side
let slot = text.parse::<u32>()
    .map_err(|_| format!("slot must be a number, got: {text}"))?;

// Option -> Result with a message
let coin = Coin::parse(text).ok_or(format!("unknown coin: {text}"))?;

Searching and changing a Vec

// read-only search, returning a borrow of the item
for coin in &self.coins {
    if coin.value() == 10 { return Some(coin); }
}

// mutable pass — change an item in place
for coin in &mut self.coins {
    // *coin = Coin::Dime;
}

// keep only what matches
self.coins.retain(|coin| coin.value() > 5);

// the short forms — |coin| ... is a closure (ch 13); both are worth knowing now
self.coins.iter().find(|coin| coin.value() == 10)    // -> Option<&Coin>
self.coins.iter().position(|coin| coin.value() == 10) // -> Option<usize>

A plain for loop does everything here. Use it if the closure forms feel unfamiliar — clarity beats brevity while you rebuild.

Exiting with a status code

eprintln!("error: {message}");    // stderr, not stdout
std::process::exit(1);

Suggested order

Not stages — just the order that keeps the compiler useful. Run cargo test after each.

1. lib.rs + task.rs. Four tests should go green. This proves your module wiring works before any logic exists.
2. command.rs. Four more. The rejects_bad_input test is the interesting one.
3. store.rs. The remaining nine.
4. main.rs. Untested — verify by running the session from the top of this page yourself.

Hints

Ten minutes stuck on the same thing first. Earlier than that and you are buying a smaller lesson.

Done means

• cargo test → 17 passed; 0 failed.
• Every session line at the top of this page reproduces.
• Failures print to stderr and exit non-zero: cargo run -q -- fly; echo $? → 1.
• cargo build is warning-free. Warnings are findings, not noise — read each one.
• Store's fields are private, and nothing outside store.rs needs them.

Stretch goals

Only after 17/17. Each one drags in the next chapter you will need for backend work:

1. Display instead of label(). Implement std::fmt::Display for Status and Priority, then print with {}. This is your first hand-written trait impl (ch10). Keep label() so the tests still pass.
2. An error enum. Replace String errors with enum TaskError { UnknownCommand(String), NotFound(u32), ... }. You will need Display on it, and the tests will keep passing since they only check is_err(). This is how real Rust reports errors.
3. A start command that sets Status::InProgress — and notice how the compiler lists every match you now have to update. That is exhaustiveness paying you back.
4. Sort list by priority, high first. Needs #[derive(PartialOrd, Ord)] and awareness that variant declaration order defines the ordering.
5. Persist to a file between runs. Plain text is enough; no dependencies needed. This is where ?, io::Error, and real error mixing stop being an exercise.