cliard24 🃏

The project name is a combination of CLI (Command Line Interface), Card, and 24 (game objective), indicating a 24-point game played through the command line.

English | 简体中文

🎯 Project Introduction

cliard24 is a 24-point card game implemented in Rust that runs in the command line interface. It offers two modes:

• 🎲 Game Mode: Play the classic 24-point game interactively in the command line
• 🔍 Solver Mode: Compute all possible expressions for any combination of numbers to reach a target value

📝 What is the 24-point game?

The 24-point game is a classic mathematical puzzle where players use addition, subtraction, multiplication, and division to combine the values of 4 playing cards to make 24.

🚀 Quick Start

📦 Installation Methods

Method 1: crates.io (Recommended)

cargo install cliard24

After successful installation, the executable will be placed in Cargo's binary directory (typically ~/.cargo/bin/)

Method 2: Source Compilation

git clone https://github.com/Expien1/cliard24.git
cd cliard24
cargo build --release

After successful compilation, the executable is located at ./target/release/cliard24

🎮 Game Mode Usage Examples

# Start interactive game (using default parameters)
cliard24

# Explicitly specify game mode
cliard24 play

# Endless mode (unlimited rounds, suitable for practice)
cliard24 play --endless

# Customize attempt limit and solution display limit
cliard24 play --max-attempts 5 --limit 3

Parameter Description:

• --max-attempts or -a: Maximum attempts per round (default: 3, 0 means unlimited)
• --limit or -l: Limit on the number of solutions displayed (default: 1, 0 means display all)
• --endless or -e: Enable endless mode (default: false)

🔍 Solver Mode Usage Examples

# Solve classic 24-point puzzle (3,3,8,8)
cliard24 solve 3 3 8 8

# Custom target value (find expressions for 1,2,3,4 to reach 10)
cliard24 solve 1 2 3 4 --target 10

# Limit displayed solution count (avoid excessive output)
cliard24 solve 1 2 3 4 5 --limit 5

Parameter Description:

• Number list: At least 2 numbers, separated by spaces, supports decimals (⚠️ Negative numbers not currently supported)
• --target or -t: Target value (default: 24)
• --limit or -l: Limit on the number of solutions displayed (default: 0, display all)

📐 Game Rules and Operations

Classic 24-Point Game Rules

1. Start: Randomly draw 4 playing cards
2. Card Values: A=1, J=11, Q=12, K=13, other cards use their face value
3. Operators: Only addition (+), subtraction (-), multiplication (*), and division (/) are allowed
4. Usage Restriction: Each card must be used exactly once
5. Parentheses: Arbitrary levels of parentheses nesting are supported
6. Win Condition: The expression evaluates to 24 (or the specified target value in solver mode)

Expression Input Formats

In game mode, the following expression types are supported:

Game Interaction Commands

In game mode, in addition to entering expressions, the following commands are available:

🖼️ Game Interface Examples

🏗️ Technical Implementation

Project Features

• Complete expression parsing, evaluation, and validation implementation
• Uses only 3 third-party libraries (clap, rand, thiserror)
• Modular design with 3 modules: expression tree, playing cards, and TUI

Project Architecture

cliard24/
├── src/
│   ├── main.rs             # Command line entry, parameter parsing and dispatch, depends on clap
│   ├── expression/
│   │   ├── mod.rs          # Expression tree module exports
│   │   ├── ast.rs          # Expression tree data structure and basic operations (including evaluation)
│   │   ├── parser.rs       # Expression string parser
│   │   ├── solver.rs       # Expression solver (exhaustive search)
│   │   └── error.rs        # Expression tree error type definitions, depends on thiserror
│   ├── playing_cards/
│   │   ├── mod.rs          # Playing card simulation module exports
│   │   ├── card.rs         # Playing card data structure representation and ASCII rendering
│   │   └── generator.rs    # Deck management and random card drawing, depends on rand
│   └── tui/
│       ├── mod.rs          # TUI interaction module exports
│       ├── game_mode.rs    # Interactive game main loop
│       ├── solve_mode.rs   # Solver mode input processing
│       └── error.rs        # Game error type definitions, depends on thiserror
└── Cargo.toml              # Project configuration and dependency declaration

Module Dependencies

⚠️ Notes and Explanations

💬 About AI-Generated Comments

After completing the code development for this project, I used AI to check code readability and generate English comments. The AI helped optimize some variable names, function names, and added detailed English comments. If you want to view the original version of the code comments, you can check the Git history.

I personally believe there are many benefits to using AI to help review code readability and write comments. First, it increases writing efficiency; second, AI's comment style and terminology are more consistent; and I found that the quality of comments written by AI is higher than my handwritten ones—it helps me express my design intentions more clearly.

Although AI-generated comments are useful, it's important to be cautious about AI-generated content. For complex or incorrect logic, AI might misunderstand or further deepen errors, so complex logic code and the generated comments still require manual review.

📝 Project Nature Statement

This project is a personal learning project, and my implementation represents just one feasible approach.

• There is still much room for optimization (algorithms, performance, code structure, etc.)
• Please do not regard it as the "standard answer" or "best practice"
• Suggestions for improvement are welcome

📜 English Translation Note

• This English version of the README was translated from Chinese by AI.
• The AI comment prompts I used are not included in the English version; they are placed in the Chinese README.

🙏 Acknowledgments

• Thanks to the inventor of the 24-point game, who provided the core design inspiration for this project and allowed me to experience the joy of problem-solving in my childhood.
• Thanks to the Rust language and its ecosystem for providing a stable and efficient toolchain for this project's implementation, as well as the maintainers of the open-source libraries this project depends on (clap, rand, thiserror).
• Thanks to the contributors and researchers of the relevant algorithms used in this project (expression parsing, expression tree construction, backtracking search, etc.).