Pular para o conteúdo
Rust em Português

Lição 18 de 18 · 60 min

Projeto final: lista de tarefas no terminal

Junte tudo o que aprendeu num programa de verdade, uma lista de tarefas no terminal que adiciona, lista, conclui, remove e salva em arquivo.

Ao terminar, você vai saber:

  • Ler argumentos da linha de comando com std::env::args
  • Modelar o programa com uma struct Tarefa e um enum Comando
  • Tratar todos os erros com Result e o operador ?
  • Salvar e carregar dados num arquivo de texto com std::fs
  • Saber por onde continuar estudando Rust

Chegou a hora de juntar as peças. Você vai construir um programa de terminal para cuidar das tarefas do dia, do jeito que muita ferramenta de verdade funciona:

cargo run -- adicionar Pagar o boleto da luz
cargo run -- listar
cargo run -- concluir 1
cargo run -- remover 1

As tarefas ficam salvas num arquivo tarefas.txt, então nada se perde quando o programa termina. Tudo só com a biblioteca padrão, sem nenhuma dependência.

O código vem em passos. Cada passo é um pedaço do mesmo arquivo src/main.rs. Cole um embaixo do outro, na ordem, e no fim você terá o programa completo.

Passo 1: criar o projeto

cargo new tarefas
cd tarefas

Apague o conteúdo de src/main.rs. Vamos escrever tudo do zero.

Passo 2: imports e a struct Tarefa

use std::env;
use std::fs;
use std::process;

const ARQUIVO: &str = "tarefas.txt";

#[derive(Debug, Clone, PartialEq)]
struct Tarefa {
    descricao: String,
    concluida: bool,
}

impl Tarefa {
    fn new(descricao: &str) -> Self {
        Self {
            descricao: String::from(descricao),
            concluida: false,
        }
    }

    /// Transforma a tarefa em uma linha do arquivo.
    fn para_linha(&self) -> String {
        let marca = if self.concluida { "[x]" } else { "[ ]" };
        format!("{marca} {}", self.descricao)
    }

    /// Lê uma linha do arquivo. Devolve None se a linha não estiver no formato.
    fn de_linha(linha: &str) -> Option<Tarefa> {
        if let Some(resto) = linha.strip_prefix("[x] ") {
            Some(Tarefa { descricao: resto.to_string(), concluida: true })
        } else if let Some(resto) = linha.strip_prefix("[ ] ") {
            Some(Tarefa { descricao: resto.to_string(), concluida: false })
        } else {
            None
        }
    }
}

O formato do arquivo é pensado para gente ler também. Cada linha é uma tarefa, com [ ] para pendente e [x] para concluída:

[x] Pagar o boleto da luz
[ ] Estudar Rust

O método strip_prefix devolve Some(resto) se o texto começa com aquele prefixo, e None se não começa. Combinado com if let, ele faz o trabalho de ler a linha. Uma linha estragada vira None, e não um travamento.

const declara uma constante: um valor fixo, com o tipo escrito, conhecido na compilação.

Passo 3: o enum Comando

O usuário pode pedir quatro coisas. Isso tem cara de enum:

#[derive(Debug, PartialEq)]
enum Comando {
    Adicionar(String),
    Listar,
    Concluir(usize),
    Remover(usize),
}

Cada variante carrega só o que precisa: o texto da tarefa nova ou o número da tarefa.

Passo 4: ler os argumentos

std::env::args() entrega as palavras digitadas no terminal. A primeira (posição 0) é o caminho do próprio programa. Em cargo run -- concluir 2, chegam três: o programa, concluir e 2. O -- serve para separar os argumentos do Cargo dos argumentos do seu programa.

fn ler_numero(texto: Option<&String>) -> Result<usize, String> {
    let Some(texto) = texto else {
        return Err(String::from("faltou o número da tarefa"));
    };
    let numero: usize = texto
        .parse()
        .map_err(|_| format!("\"{texto}\" não é um número válido"))?;
    if numero == 0 {
        return Err(String::from("as tarefas começam no número 1"));
    }
    Ok(numero)
}

fn interpretar(args: &[String]) -> Result<Comando, String> {
    let Some(acao) = args.get(1) else {
        return Err(String::from("diga o que fazer: adicionar, listar, concluir ou remover"));
    };

    match acao.as_str() {
        "adicionar" => {
            // Junta todas as palavras depois de "adicionar"
            let texto = args[2..].join(" ");
            if texto.trim().is_empty() {
                return Err(String::from("escreva a descrição da tarefa"));
            }
            Ok(Comando::Adicionar(texto))
        }
        "listar" => Ok(Comando::Listar),
        "concluir" => Ok(Comando::Concluir(ler_numero(args.get(2))?)),
        "remover" => Ok(Comando::Remover(ler_numero(args.get(2))?)),
        outro => Err(format!("comando desconhecido: {outro}")),
    }
}

Aqui aparece muito do que você viu nas lições anteriores:

  • args.get(1) devolve Option, porque o usuário pode não ter digitado nada. O let else sai cedo nesse caso.
  • Os erros são do tipo String: uma mensagem pronta para mostrar. Para um programa pequeno, é o bastante.
  • map_err troca o erro do parse (que é técnico, em inglês) por uma mensagem nossa. Depois o ? devolve esse erro se der problema.
  • acao.as_str() transforma a String em &str para o match poder comparar com textos literais.
  • O último braço, outro, casa com qualquer texto e ainda dá um nome a ele.

Passo 5: carregar e salvar

fn carregar() -> Result<Vec<Tarefa>, String> {
    match fs::read_to_string(ARQUIVO) {
        Ok(conteudo) => Ok(conteudo.lines().filter_map(Tarefa::de_linha).collect()),
        // Primeira vez: o arquivo ainda não existe, então a lista começa vazia
        Err(erro) if erro.kind() == std::io::ErrorKind::NotFound => Ok(Vec::new()),
        Err(erro) => Err(format!("não consegui ler {ARQUIVO}: {erro}")),
    }
}

fn salvar(tarefas: &[Tarefa]) -> Result<(), String> {
    let mut conteudo = String::new();
    for tarefa in tarefas {
        conteudo.push_str(&tarefa.para_linha());
        conteudo.push('\n');
    }
    fs::write(ARQUIVO, conteudo).map_err(|erro| format!("não consegui salvar {ARQUIVO}: {erro}"))
}

fs::read_to_string lê o arquivo inteiro numa String, e fs::write grava uma String num arquivo, substituindo o que havia. As duas devolvem Result, porque mexer em disco pode falhar: falta de permissão, disco cheio.

Duas novidades:

  • filter_map é como um map que joga fora os None. Cada linha passa por Tarefa::de_linha; as válidas viram tarefas, as estragadas somem.
  • O if depois do padrão, em Err(erro) if ..., é uma guarda: o braço só casa se a condição também for verdadeira. Assim o “arquivo não existe” ganha um tratamento especial, e os outros erros caem no último braço.

Passo 6: executar o comando

fn listar(tarefas: &[Tarefa]) {
    if tarefas.is_empty() {
        println!("Nenhuma tarefa. Aproveite o dia!");
        return;
    }
    for (i, tarefa) in tarefas.iter().enumerate() {
        println!("{}. {}", i + 1, tarefa.para_linha());
    }
}

fn executar(comando: Comando, tarefas: &mut Vec<Tarefa>) -> Result<(), String> {
    match comando {
        Comando::Adicionar(texto) => {
            tarefas.push(Tarefa::new(&texto));
            println!("Tarefa {} adicionada: {texto}", tarefas.len());
        }
        Comando::Listar => listar(tarefas),
        Comando::Concluir(numero) => {
            let Some(tarefa) = tarefas.get_mut(numero - 1) else {
                return Err(format!("não existe a tarefa {numero}"));
            };
            tarefa.concluida = true;
            println!("Concluída: {}", tarefa.descricao);
        }
        Comando::Remover(numero) => {
            if numero > tarefas.len() {
                return Err(format!("não existe a tarefa {numero}"));
            }
            let removida = tarefas.remove(numero - 1);
            println!("Removida: {}", removida.descricao);
        }
    }
    Ok(())
}

Para o usuário, a primeira tarefa é a 1. Para o Vec, é a 0. Por isso o numero - 1. O ler_numero já recusou o zero, então a conta nunca fica negativa.

get_mut é o irmão do get: devolve Option<&mut Tarefa>, uma referência que permite alterar. E o remove tira o item da posição e devolve ele, para você ainda mostrar o nome.

O match em comando cobre as quatro variantes. Se um dia você criar uma quinta, o compilador aponta este lugar.

Passo 7: a função main

fn rodar() -> Result<(), String> {
    let args: Vec<String> = env::args().collect();
    let comando = interpretar(&args)?;
    let mut tarefas = carregar()?;
    let precisa_salvar = comando != Comando::Listar;

    executar(comando, &mut tarefas)?;

    if precisa_salvar {
        salvar(&tarefas)?;
    }
    Ok(())
}

fn main() {
    if let Err(erro) = rodar() {
        eprintln!("Erro: {erro}");
        process::exit(1);
    }
}

A rodar concentra o caminho feliz, com um ? em cada passo que pode falhar. A main só cuida do erro: eprintln! escreve na saída de erros (e não na saída normal) e process::exit(1) encerra com código 1, que no terminal significa “deu errado”. Scripts e outras ferramentas usam esse código para saber se o comando funcionou.

Passo 8: alguns testes

Para fechar, aproveite o que viu em Testes:

#[cfg(test)]
mod tests {
    use super::*;

    fn args(texto: &str) -> Vec<String> {
        texto.split_whitespace().map(String::from).collect()
    }

    #[test]
    fn interpreta_adicionar_com_varias_palavras() {
        let comando = interpretar(&args("tarefas adicionar pagar o boleto"));
        assert_eq!(comando, Ok(Comando::Adicionar(String::from("pagar o boleto"))));
    }

    #[test]
    fn numero_invalido_vira_erro() {
        assert!(interpretar(&args("tarefas concluir dois")).is_err());
        assert!(interpretar(&args("tarefas remover 0")).is_err());
    }

    #[test]
    fn linha_vai_e_volta() {
        let mut tarefa = Tarefa::new("ligar para o contador");
        tarefa.concluida = true;
        assert_eq!(Tarefa::de_linha(&tarefa.para_linha()), Some(tarefa));
    }
}

Os derive(PartialEq) que colocamos lá no começo servem justamente para o assert_eq! conseguir comparar Comando e Tarefa.

Rodando

cargo test
cargo run -- adicionar Comprar pão na padaria
cargo run -- adicionar Pagar o boleto da luz
cargo run -- concluir 2
cargo run -- listar
1. [ ] Comprar pão na padaria
2. [x] Pagar o boleto da luz

Teste também os erros: cargo run -- concluir 9, cargo run -- concluir abc, cargo run -- voar. Nenhum deles derruba o programa com panic!. Todos viram uma mensagem clara.

Quando estiver satisfeito, cargo build --release gera um executável otimizado em target/release/tarefas, que roda sem o Cargo.

Ideias para continuar

O programa funciona, mas dá para ir longe:

  • serde e serde_json: salvar em JSON em vez do formato próprio, com data de criação e prioridade. O serde converte structs em JSON e de volta com um derive.
  • clap: ler argumentos com ajuda automática (--help), atalhos e validação, sem escrever o interpretar à mão.
  • Organizar em módulos: mover Tarefa para src/tarefa.rs e o arquivo para src/armazenamento.rs, como em Módulos e crates.
  • Erro próprio: trocar String por um enum de erro, como em Option e Result.

Próximos passos de estudo

  • The Rust Programming Language, o livro oficial, gratuito em doc.rust-lang.org/book. Conhecido como “o livro”. Vale ler do começo ao fim agora que você já tem a base.
  • Rustlings (github.com/rust-lang/rustlings): pequenos exercícios que você corrige até o compilador ficar feliz. Ótimo para fixar.
  • Exercism (exercism.org/tracks/rust): exercícios com testes prontos e, se quiser, revisão de mentores.
  • Rust by Example (doc.rust-lang.org/rust-by-example): o mesmo conteúdo do livro, mostrado com exemplos curtos que rodam no navegador.
  • Comunidade brasileira: há grupos de Rust em português no Telegram e no Discord, além de encontros em várias cidades. Pesquise por “Rust Brasil” e participe. Perguntar é o jeito mais rápido de aprender.

Parabéns por chegar até aqui. Você saiu do “olá, mundo” para um programa com estrutura, tratamento de erro, testes e arquivo em disco. Isso é Rust de verdade.

Resumo

  • std::env::args() lê os argumentos; a posição 0 é o próprio programa.
  • Uma struct modela o dado (Tarefa) e um enum modela as ações (Comando).
  • Result<_, String> e o operador ? levam qualquer erro até a main, que mostra a mensagem e sai com código 1.
  • fs::read_to_string e fs::write leem e gravam arquivos de texto.
  • Guardas (if depois do padrão) e filter_map deixam o tratamento de casos especiais curto.

Desafio

Acrescente o comando limpar, que remove de uma vez todas as tarefas concluídas e mostra quantas saíram. Dica: o Vec tem o método retain, que mantém só os itens para os quais a closure devolve true.

Ver uma resposta
// 1. No enum Comando, acrescente a variante:
//        Limpar,
//
// 2. Em interpretar, acrescente o braço:
//        "limpar" => Ok(Comando::Limpar),
//
// 3. Em executar, acrescente o braço abaixo.

#[derive(Debug)]
struct Tarefa {
    descricao: String,
    concluida: bool,
}

enum Comando {
    Limpar,
}

fn executar(comando: Comando, tarefas: &mut Vec<Tarefa>) -> Result<(), String> {
    match comando {
        Comando::Limpar => {
            let antes = tarefas.len();
            tarefas.retain(|tarefa| !tarefa.concluida);
            println!("{} tarefa(s) concluída(s) removida(s)", antes - tarefas.len());
        }
    }
    Ok(())
}

fn main() {
    // Teste rápido, fora do projeto
    let mut tarefas = vec![
        Tarefa { descricao: String::from("Pagar o boleto"), concluida: true },
        Tarefa { descricao: String::from("Estudar Rust"), concluida: false },
    ];
    executar(Comando::Limpar, &mut tarefas).unwrap();
    println!("{:?}", tarefas);
}
Salvo só neste navegador.