fortune-rs 🎲

A modern, feature-rich implementation of the classic BSD fortune program in Rust. This implementation aims to be a drop-in replacement for traditional fortune programs on Unix-like systems while maintaining compatibility with various fortune database formats.

📑 Table of Contents

• fortune-rs 🎲
  • 📑 Table of Contents
  • ✨ Features
  • 📥 Installation
    • From Source
  • 🚀 Usage
    • Basic Usage
    • Common Options
    • Advanced Usage
  • 🛠 Development
    • Project Structure
    • Building
    • Testing
      • Test Coverage
  • 🔧 Implementation Details
  • 🗺 Roadmap
    • Current Status
    • Future Plans
  • 👥 Contributing
  • 📄 License
  • 📚 References
    • Rust Implementations

✨ Features

• 🔄 Full compatibility with traditional fortune program options
• 📚 Support for multiple fortune database formats
• 🔍 Pattern matching with regular expressions
• 📊 Weighted fortune selection
• 🌳 Recursive directory searching
• 📏 Precise control over fortune length
• 🎨 Support for both regular and offensive fortunes
• 🐛 Debug output for troubleshooting

📥 Installation

From Source

# Clone the repository
git clone https://github.com/twang2218/fortune-rs.git

# Change into the directory
cd fortune-rs

# Build with optimizations
cargo build --release

The compiled binary will be available at target/release/fortune

🚀 Usage

Basic Usage

# Display a random fortune
fortune

# Display a random fortune from specific files or directories
fortune /path/to/fortune/file

# Display a random offensive fortune
fortune -o

Common Options

Advanced Usage

# Pattern matching (case-insensitive)
fortune -i -m "pattern"

# Short fortunes only
fortune -s

# Show fortune sources
fortune -c

# List available fortune files
fortune -f

# Weighted selection
fortune 30% /path/to/fortunes1 70% /path/to/fortunes2

🛠 Development

Project Structure

fortune-rs/
├── src/
│   ├── fortune.rs    # Main implementation
│   ├── strfile.rs    # Database generator
│   └── metadata.rs   # Metadata handling
├── tests/
│   ├── integration.rs # Integration tests
│   ├── data/         # Test files
│   └── data2/        # Additional tests
└── Cargo.toml        # Project manifest

Building

# Debug build
cargo build

# Release build with optimizations
cargo build --release

Testing

# Run all tests
cargo test

Test Coverage

• ✅ Pattern matching (-m)
• ✅ Case-insensitive search (-i)
• ✅ Length-based filtering (-l, -s, -n)
• ✅ File listing (-f)
• ✅ Weighted selection
• ✅ Offensive fortunes (-o)
• ✅ Equal-size handling (-e)

🔧 Implementation Details

• ✅ Compatible with traditional fortune database formats
• ✅ Supports regular and offensive fortunes
• ✅ Implements weighted selection
• ✅ Pattern matching with regex
• ✅ Recursive directory traversal
• ✅ Multiple file formats and encodings
• ✅ Strfile index compatibility

🗺 Roadmap

Current Status

• ✅ Core Functionality

  • ✅ Random fortune display
  • ✅ Strfile index support
  • ✅ Directory searching

• ✅ Traditional Options

  • ✅ Standard flags
  • ✅ Pattern matching
  • ✅ Length control
  • ✅ Debug output

Future Plans

• 🔄 Modern Enhancements

  • ⏳ TOML configuration
  • ⏳ Embedded fortune database

• 📈 Project Growth

  • ⏳ Extended docs
  • ✅ Comprehensive testing
  • ⏳ CI/CD pipeline

👥 Contributing

We welcome contributions! Here's how you can help:

1. 🍴 Fork the repository
2. 🌿 Create a branch for your feature
3. ✅ Add tests for new features
4. 🧪 Ensure all tests pass
5. 📬 Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 References

Rust Implementations

• cmatsuoka/fortune-rs, by Claudio Matsuoka, Brazil, at 2017;
• c-OO-b/rust-fortune, by c-OO-b, Norway, at 2019;
• wapm-packages/fortune, forked from c-OO-b/rust-fortune, at 2019;
• runebaas/fortune-mod.rs, by Daan Boerlage, Switzerland, at 2019;
• kvrohit/fortune, by Rohit K Viswanath, at 2020;
• davidkna/lolcow-fortune-rs, by David Knaack, Berlin, Germany, at 2021;
• blackbird1128/fortune_cookie, by Alexj, at 2023;
• zuisong/rs-fortune, by ZuiSong, Changsha, China, at 2023;
• cafkafk/fortune-kind, by Christina Sørensen, Denmark, at 2023;
• rilysh/fortune-day, at 2024;
• FaceFTW/shell-toy, by Alex Westerman, at 2024;