added interactive inputs, better error messages, bugfixes

2025-11-03 20:55:45 +01:00
parent 2336ce0325
commit d289cff56c
17 changed files with 955 additions and 55 deletions
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -14,6 +14,7 @@
 - [Loops](./language/loops.md)
 - [Parallel Execution](./language/parallel.md)
 - [Built-in Variables](./language/builtins.md)
+- [User Input](./language/input.md)

 # Examples

--- a/docs/src/language/input.md
+++ b/docs/src/language/input.md
@@ -0,0 +1,347 @@
+# User Input
+
+> ⚠️ This documentation is AI-generated and may contain errors.
+
+Rush provides several built-in functions for interactive user input, making it easy to create interactive scripts and tools.
+
+## Input Functions
+
+### `input()`
+
+Read a line of text from the user.
+
+**Syntax:**
+```rush
+VARIABLE = input()
+VARIABLE = input("prompt")
+```
+
+**Examples:**
+```rush
+# With prompt
+NAME = input("What is your name? ")
+echo "Hello, $NAME!"
+
+# Without prompt
+echo "Enter a value:"
+VALUE = input()
+echo "You entered: $VALUE"
+```
+
+**Use cases:**
+- Collecting user information
+- Reading configuration values
+- Interactive script parameters
+
+---
+
+### `confirm()`
+
+Ask a yes/no question and get a boolean response.
+
+**Syntax:**
+```rush
+VARIABLE = confirm("question")
+```
+
+**Returns:**
+- `1` for yes (y/yes/Y/YES)
+- `0` for no (n/no/N/NO)
+
+**Examples:**
+```rush
+PROCEED = confirm("Do you want to continue?")
+
+if $PROCEED {
+    echo "Continuing..."
+} else {
+    echo "Stopped."
+    exit 0
+}
+```
+
+```rush
+# Check before dangerous operation
+DELETE_CONFIRM = confirm("Are you sure you want to delete all files?")
+
+if not $DELETE_CONFIRM {
+    echo "Operation cancelled."
+    exit 1
+}
+
+echo "Deleting files..."
+```
+
+**Use cases:**
+- Confirmations before destructive actions
+- Binary choices
+- Permission checks
+
+---
+
+### `select()`
+
+Display a menu and let the user select one option.
+
+**Syntax:**
+```rush
+CHOICE = select("prompt", "option1", "option2", "option3", ...)
+```
+
+**Returns:**
+- A number representing the selected option (1-indexed)
+- `0` if cancelled or error
+
+**Examples:**
+```rush
+ENV = select("Select environment:", "Development", "Staging", "Production")
+
+if $ENV {
+    echo "Selected environment: $ENV"
+}
+```
+
+```rush
+# Using the result
+LANG = select("Choose language:", "English", "Spanish", "French", "German")
+
+# Process based on selection
+if $LANG {
+    echo "You selected option $LANG"
+}
+```
+
+**Display:**
+```
+Choose language:
+
+  1. English
+  2. Spanish
+  3. French
+  4. German
+
+Select (1-4): 
+```
+
+**Use cases:**
+- Environment selection
+- Configuration options
+- Mode selection
+- File/directory choice
+
+---
+
+### `multiselect()`
+
+Display a menu and let the user select multiple options.
+
+**Syntax:**
+```rush
+CHOICES = multiselect("prompt", "option1", "option2", "option3", ...)
+```
+
+**Returns:**
+- A comma-separated string of selected indices (e.g., "1,3,5")
+- Empty string if none selected or error
+
+**Input format:**
+- Comma-separated: `1,2,3`
+- Space-separated: `1 2 3`
+- Mixed: `1, 2, 3`
+
+**Examples:**
+```rush
+COMPONENTS = multiselect("Select components to install:", "Core", "Database", "Web Server", "Cache", "Monitoring")
+
+echo "Selected components: $COMPONENTS"
+```
+
+```rush
+# Feature flags
+FEATURES = multiselect("Enable features:", "Logging", "Analytics", "Notifications", "Dark Mode", "Auto-save")
+
+echo "Enabled features: $FEATURES"
+```
+
+**Display:**
+```
+Select components to install:
+
+  1. Core
+  2. Database
+  3. Web Server
+  4. Cache
+  5. Monitoring
+
+Select multiple (e.g., 1,2,3 or 1 2 3): 
+```
+
+**Use cases:**
+- Component selection
+- Feature flags
+- Multiple file selection
+- Task selection
+
+---
+
+## Complete Example
+
+Here's a complete interactive script demonstrating all input methods:
+
+```rush
+#!/usr/bin/env rush
+
+echo "=== Project Setup Wizard ==="
+echo ""
+
+# Get project details
+PROJECT_NAME = input("Project name: ")
+DESCRIPTION = input("Description: ")
+
+echo ""
+
+# Select project type
+PROJECT_TYPE = select("Project type:", "Web Application", "CLI Tool", "Library", "API Service")
+
+echo ""
+
+# Select features
+FEATURES = multiselect("Select features:", "Authentication", "Database", "API", "Testing", "Documentation")
+
+echo ""
+
+# Confirm setup
+PROCEED = confirm("Create project with these settings?")
+
+if not $PROCEED {
+    echo "Setup cancelled."
+    exit 1
+}
+
+echo ""
+echo "=== Creating Project ==="
+echo "Name: $PROJECT_NAME"
+echo "Description: $DESCRIPTION"
+echo "Type: $PROJECT_TYPE"
+echo "Features: $FEATURES"
+echo ""
+echo "Project created successfully!"
+```
+
+---
+
+## Patterns and Best Practices
+
+### Input Validation
+
+Always validate user input:
+
+```rush
+AGE = input("Enter your age: ")
+
+# Basic validation (you can add more sophisticated checks)
+if not $AGE {
+    echo "Age is required"
+    exit 1
+}
+
+echo "Age: $AGE"
+```
+
+### Required Confirmations
+
+For destructive operations, always confirm:
+
+```rush
+echo "WARNING: This will delete all data!"
+CONFIRMED = confirm("Are you absolutely sure?")
+
+if not $CONFIRMED {
+    echo "Operation cancelled."
+    exit 0
+}
+
+# Proceed with destructive operation
+echo "Deleting data..."
+```
+
+### Menu-driven Scripts
+
+Create interactive menus for complex workflows:
+
+```rush
+echo "=== Main Menu ==="
+ACTION = select("What would you like to do?", "Install", "Update", "Remove", "Configure", "Exit")
+
+# Handle selection
+# ... process based on $ACTION value
+```
+
+### Progressive Input
+
+Collect information step by step:
+
+```rush
+echo "Step 1: User Information"
+USERNAME = input("Username: ")
+
+echo ""
+echo "Step 2: Preferences"
+THEME = select("Theme:", "Light", "Dark", "Auto")
+
+echo ""
+echo "Step 3: Features"
+FEATURES = multiselect("Features:", "Feature A", "Feature B", "Feature C")
+
+echo ""
+CONFIRM = confirm("Save these settings?")
+
+if $CONFIRM {
+    echo "Settings saved!"
+}
+```
+
+---
+
+## Error Handling
+
+Input functions handle errors gracefully:
+
+- `input()` - Returns empty string on EOF
+- `confirm()` - Keeps prompting until valid input (y/n)
+- `select()` - Returns 0 on error, keeps prompting for valid range
+- `multiselect()` - Returns empty string on error, validates range
+
+**Example:**
+```rush
+# Check for empty input
+NAME = input("Name: ")
+
+if not $NAME {
+    echo "Error: Name cannot be empty"
+    exit 1
+}
+
+echo "Hello, $NAME!"
+```
+
+---
+
+## Tips
+
+1. **Clear prompts** - Make prompts descriptive and include examples
+2. **Show options** - For select/multiselect, use clear, concise option names
+3. **Confirm destructive actions** - Always use `confirm()` before dangerous operations
+4. **Validate input** - Check that required inputs are provided
+5. **Provide feedback** - Echo back what the user selected for confirmation
+
+---
+
+## Limitations
+
+- Input is line-based (no character-by-character input)
+- No built-in password masking (input is visible)
+- No default values (yet)
+- No input history or autocomplete
+
+These features may be added in future versions.