stdin-helper

A simple, intuitive Rust library for reading typed user input from stdin. Stop fighting with read_line() and parsing - just ask for what you need.

What is this?

stdin-helper provides straightforward functions for getting typed input from the user. If you've ever been frustrated writing the same read_line() boilerplate over and over, this library is for you.

The functions automatically retry when given invalid input. Ask for an integer and the user types "hello"? It will ask again until it gets a valid number.

Quick Start

Add to your Cargo.toml:

[dependencies]
stdin-helper = "1.0.1"

Or use cargo:

cargo add stdin-helper

Basic Usage

use stdin_helper::{get_string, get_i32, get_f64, get_bool};

fn main() {
    let name = get_string("What's your name? ");
    let age = get_i32("How old are you? ");
    let height = get_f64("Height in meters: ");
    let verified = get_bool("Are you human? ");

    println!("{} is {} years old and {:.2}m tall", name, age, height);
}

Available Functions

String Input

Integer Types

Unsigned Integer Types

Floating Point Types

Boolean Input

Generic Input

If you need a type not listed above, use the generic function:

use stdin_helper::get_input;

let value: u64 = get_input("Enter a value: ");

Examples

Simple Calculator

use stdin_helper::{get_i32, get_string};

fn main() {
    let x = get_i32("First number: ");
    let op = get_string("Operator (+, -, *, /): ");
    let y = get_i32("Second number: ");

    let result = match op.as_str() {
        "+" => x + y,
        "-" => x - y,
        "*" => x * y,
        "/" => x / y,
        _ => {
            println!("Invalid operator");
            return;
        }
    };

    println!("{} {} {} = {}", x, op, y, result);
}

Temperature Converter

use stdin_helper::{get_f64, get_string};

fn main() {
    let temp = get_f64("Enter temperature: ");
    let unit = get_string("Unit (C/F): ").to_uppercase();

    match unit.as_str() {
        "C" => {
            let fahrenheit = (temp * 9.0 / 5.0) + 32.0;
            println!("{}°C = {:.1}°F", temp, fahrenheit);
        }
        "F" => {
            let celsius = (temp - 32.0) * 5.0 / 9.0;
            println!("{}°F = {:.1}°C", temp, celsius);
        }
        _ => println!("Invalid unit. Use C or F."),
    }
}

Grade Calculator

use stdin_helper::{get_f32, get_i32};

fn main() {
    let num_grades = get_i32("How many grades? ");
    let mut sum = 0.0;

    for i in 1..=num_grades {
        let grade = get_f32(&format!("Grade {}: ", i));
        sum += grade;
    }

    let average = sum / num_grades as f32;
    println!("Average: {:.2}", average);
}

How It Works

Each function displays your prompt and waits for input. If the input can't be parsed into the requested type, the prompt appears again. This continues until valid input is received.

This approach is perfect for learning, prototyping, and simple CLI tools. For production applications where you need fine-grained error handling, you might want more control over the retry logic.

Future Plans

Note: The features described below are planned for future releases and are not yet implemented.

In upcoming versions, stdin-helper will support a builder pattern API for advanced input validation:

// THIS DOES NOT WORK YET - Coming in a future version!
use stdin_helper::get_input;

let user_rating: u32 = get_input()
    .prompt("Please input a rate: ")
    .range(1..=10, "Number must be between 1 and 10")
    .on_error("That doesn't look like a number")
    .expect("Failed to read input");

This will allow you to:

• Define custom validation rules
• Provide specific error messages for different validation failures
• Choose whether to retry automatically or return a Result
• Set retry limits
• Add custom validators with closures

If you'd like to contribute to making this happen, check out the repository!

Building and Testing

# Build the library
cargo build

# Run tests (coming soon)
cargo test

# Generate documentation
cargo doc --open

Why Use This?

For beginners: Eliminates boilerplate so you can focus on learning Rust concepts rather than input handling mechanics.

For prototyping: Quickly test ideas without writing parsing code every time.

For simple CLIs: Perfect for straightforward command-line tools where complex error handling isn't needed.

For teaching: Great for educational projects and coding exercises where input handling shouldn't be the focus.

When Not to Use This

This library is designed for simplicity, not for complex input scenarios. Consider alternatives if you need:

• Detailed error messages showing what went wrong
• Non-blocking input handling
• Input with timeout limits
• Advanced parsing with custom error types
• Production-grade validation with specific error recovery

For those cases, using std::io directly or other crates might be better choices.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Whether it's:

• Bug reports and feature requests
• Documentation improvements
• Code contributions
• Examples and use cases

Feel free to open an issue or submit a pull request.

Author

Created by Richard Dias Alves

Acknowledgments

Inspired by the frustration of writing read_line() boilerplate repeatedly. Built to make Rust's stdin interaction as simple as it should be.

Repository: https://github.com/richarddalves/stdin-helper
Crate: https://crates.io/crates/stdin-helper