Skip to content

SamuelSchlesinger/tshts

BranchesTags

Repository files navigation

TSHTS - Terminal Spreadsheet

An efficient, lightweight terminal-based spreadsheet application built in Rust. TSHTS brings the power of spreadsheet calculations to your command line with an intuitive interface, comprehensive formula support, and robust data management capabilities.

License Rust Edition

TSHTS Screenshot

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/SamuelSchlesinger/tshts.git
cd tshts

# Build and run
cargo run --release

# Or build for installation
cargo build --release
# Binary will be available at target/release/tshts

First Steps

TSHTS uses vim-style modes. The status bar shows your current mode (-- NORMAL --, -- INSERT --, -- VISUAL --, etc.).

  1. Navigate: Arrow keys or hjkl move between cells. Counts work: 5j, 10G.
  2. Edit: i / a / I / A / s / Enter enter Insert mode. o / O open a new row.
  3. Formula: Start with = for formulas (e.g., =A1+B1, =SUM(A1:A10))
  4. Visual: v (cells), V (whole row), Ctrl+V (block). Then y yank / d delete / c change / p paste.
  5. Save/Quit: Ctrl+S saves; :w / :wq / :q! work from the command palette (:).
  6. Export/Import: Ctrl+E (CSV export), Ctrl+L (CSV import), or :export <file> / :import <file>.
  7. Search: / searches across cells and formulas; n / N cycle results.
  8. Help: F1 or ? opens help. Press 0 to jump to Vim Mode reference; / searches help.

✨ Key Features

🧮 Powerful Formula Engine

  • Multi-Type System: numbers, strings, booleans, and list (range) values
  • Arithmetic: +, -, *, /, ** / ^ (power), % (modulo)
  • String Operations: & (concatenation), string literals with "quotes"
  • Comparison Operators: <, >, <=, >=, =, <>
  • Numeric Functions: SUM, AVERAGE, MIN, MAX, ABS, SQRT, ROUND, CEILING, FLOOR, INT, MOD, POWER, SIGN, LOG, LN, EXP, PI, RAND, RANDBETWEEN
  • Conditional Aggregates: SUMIF, COUNTIF, AVERAGEIF (">5", wildcards)
  • Lookup: VLOOKUP, INDEX, MATCH
  • String Functions: CONCAT, LEN, UPPER, LOWER, PROPER, TRIM, LEFT, RIGHT, MID, FIND, SUBSTITUTE, REPLACE, REPT, EXACT, CLEAN, CHAR, CODE, TEXT, VALUE, NUMBERVALUE
  • Date Functions: TODAY, NOW, DATE, YEAR, MONTH, DAY (Excel serial-day numbers)
  • Web Functions: GET(url) — non-blocking, cached for 5 min; first call returns "Loading…" and the cell auto-refreshes when the background fetch completes
  • Logical Functions: IF, AND, OR, NOT, TRUE, FALSE
  • Info Functions: ISBLANK, ISNUMBER, ISTEXT, TYPE, COUNT, COUNTA
  • Visualization: SPARKLINE(range) — unicode bar chart
  • Cell References: A1, AA123 — and absolute markers $A$1, $A1, A$1
  • Range Support: A1:C3 for any range-aware function
  • Circular Reference Detection: AST-based, prevents infinite loops
  • Undo/Redo: 1000-action history with Ctrl+Z / Ctrl+Y
  • Range Selection: Shift+Arrow keys
  • Autofill: Ctrl+D — copies formulas with relative-ref adjustment, preserving $-anchored parts

📊 Smart Interface

  • Auto-sizing Columns: Columns automatically adjust to content width
  • Manual Resize: Use + for all columns, -/_ for individual column adjustment
  • Scrolling Viewport: Navigate large spreadsheets smoothly with automatic cursor tracking
  • Visual Selection: Clear indication of current cell with range selection support
  • Status Messages: Real-time feedback for operations and file status
  • Search Highlighting: Visual highlighting of search results with navigation
  • Multiple View Modes: Normal, editing, help, file operations, and search modes

💾 File Management

  • Native Format: Human-readable .tshts files in JSON format
  • Save/Load: Ctrl+S to save, Ctrl+O to load spreadsheet files
  • CSV Support: Ctrl+E to export CSV, Ctrl+I/Ctrl+L to import CSV
  • Dependency Tracking: Automatic rebuilding of formula dependencies on load
  • Error Handling: Graceful handling of file operations with clear error messages
  • Data Integrity: Preserves formulas, values, column widths, and sheet dimensions

🎯 Why Choose TSHTS?

Performance: Built in Rust for excellent performance and memory efficiency. Handles large spreadsheets smoothly in terminal environments.

Portability: Cross-platform support (Linux, macOS, Windows) with no GUI dependencies. Perfect for servers, remote work, and headless environments.

Developer-Friendly: Clean architecture following domain-driven design principles. Comprehensive documentation, extensive test coverage, and modular structure make it easy to extend.

Modern Workflow: Git-friendly JSON format, command-line integration, and automation support. Works seamlessly with CI/CD pipelines and version control.

Rich Feature Set: Advanced formula engine with web functions (GET), string manipulation, logical operations, and mathematical functions. Real-time search, undo/redo, and smart autofill capabilities.

Current Capabilities

TSHTS provides a comprehensive spreadsheet experience with:

  • ✅ Formula Engine: Multi-type evaluation (numbers and strings) with 30+ operators and functions
  • ✅ Data Types: Full support for strings, numbers, formulas, and mixed-type operations
  • ✅ Web Integration: GET function for fetching data from URLs and APIs
  • ✅ String Processing: Comprehensive text manipulation with UPPER, LOWER, TRIM, FIND, MID, etc.
  • ✅ Mathematical Functions: SUM, AVERAGE, MIN, MAX, ABS, SQRT, ROUND, and more
  • ✅ Logical Operations: IF, AND, OR, NOT with full boolean logic support
  • ✅ Range Operations: Support for cell ranges (A1:C3) in all applicable functions
  • ✅ File Operations: Native .tshts format and CSV import/export
  • ✅ Smart UI: Responsive terminal interface with multiple interaction modes
  • ✅ Search System: Full-text search across cell values and formulas
  • ✅ Undo/Redo: Complete action history with unlimited undo levels
  • ✅ Selection Tools: Range selection and autofill with relative reference adjustment
  • ✅ Error Handling: Circular reference detection and comprehensive error reporting

Roadmap & Contributing

Upcoming features:

  • 📅 Charts & Visualization: Basic terminal-based charts (a SPARKLINE function already exists)
  • 📅 Excel format support (CSV is shipped)
  • 📅 Scripting: Lua/Python integration for custom functions
  • 📅 Collaboration: Real-time sharing capabilities
  • 📅 Plugins: Extension system for custom functionality
  • 📅 Named ranges in formulas, INDIRECT / OFFSET, conditional formatting, multi-column VLOOKUP, DATEDIF

Want to contribute? Check our issues for good first contributions. We welcome:

  • Bug reports and feature requests
  • Documentation improvements
  • Performance optimizations
  • New formula functions
  • Platform-specific enhancements

📖 Comprehensive Formula Reference

TSHTS supports a powerful multi-type formula system that handles both numbers and strings seamlessly.

🔢 Numeric Operations

Basic Arithmetic

=2+3          → 5
=10-4         → 6
=A1*B1        → Multiplies values in A1 and B1
=15/3         → 5
=2**3         → 8 (2 to the power of 3)
=10%3         → 1 (10 modulo 3)

Numeric Functions

=SUM(A1,B1,C1)        → Sum of individual cells
=SUM(A1:A10)          → Sum of range A1 through A10
=AVERAGE(A1:A10)      → Average of range
=MIN(A1:C3)           → Minimum value in range
=MAX(A1:C3)           → Maximum value in range
=ABS(-5)              → 5 (absolute value)
=SQRT(16)             → 4 (square root)
=ROUND(3.14159)       → 3 (round to integer)
=ROUND(3.14159, 2)    → 3.14 (round to 2 decimal places)

🔤 String Operations

String Literals and Concatenation

="Hello World"        → Hello World
=""                   → (empty string)
="Hello" & " " & "World"  → Hello World
="Number: " & 42      → Number: 42
="Result: " & (2+3)   → Result: 5

String Functions

=LEN("Hello")         → 5 (string length)
=UPPER("hello")       → HELLO (convert to uppercase)
=LOWER("WORLD")       → world (convert to lowercase)
=TRIM("  spaces  ")   → spaces (remove leading/trailing spaces)

String Extraction (0-based indexing)

=LEFT("Hello World", 5)    → Hello (first 5 characters)
=RIGHT("Hello World", 5)   → World (last 5 characters)
=MID("Hello World", 6, 5)  → World (5 chars starting at position 6)
=FIND("lo", "Hello")       → 3 (position of "lo" in "Hello")
=FIND("World", "Hello World")  → 6 (position of "World")

Advanced String Operations

=CONCAT("A", "B", "C")      → ABC (concatenate multiple values)
=CONCAT("Number: ", 123)    → Number: 123
=FIND("text", A1, 3)        → Find "text" in A1 starting from position 3

🌐 Web Functions

=GET("https://api.example.com/data")     → Fetch raw content from API
=GET("https://jsonplaceholder.typicode.com/posts/1") → Get JSON data
=GET("https://raw.githubusercontent.com/user/repo/main/data.csv") → Fetch CSV
=LEN(GET("https://example.com"))         → Get length of web content
=UPPER(GET("https://api.service.com"))   → Convert fetched content to uppercase

🔍 Comparisons (Work with Numbers and Strings)

=5<10             → 1 (true)
=A1>=B1           → 1 if A1 ≥ B1, 0 otherwise
="Hello"="Hello"  → 1 (string equality)
="Hello"<>"World" → 1 (string inequality)
=A1<>B1           → 1 if values are different

🧠 Logical Functions

=IF(A1>10, "High", "Low")     → Conditional with string results
=IF(A1="Hello", "Found", "Not Found")  → String condition
=AND(A1>0, B1<10)             → 1 if both conditions true
=OR(A1=0, B1=0)               → 1 if either condition true
=NOT(A1>5)                    → 1 if A1 ≤ 5

📊 Cell References and Ranges

=A1               → Value from cell A1 (auto-detects number vs string)
=A1+B1            → Sum if numeric, concatenation if mixed types
=SUM(A1:A10)      → Sum of range A1 through A10
=AVERAGE(B1:B5)   → Average of range B1 through B5
=CONCAT(A1:A3)    → Concatenate all values in range A1:A3

🔄 Type Conversion

TSHTS automatically handles type conversion:

  • Numeric operations: Strings are converted to numbers (empty/invalid = 0)
  • String operations: Numbers are converted to strings
  • Comparisons: Like types compared directly, mixed types compared as strings
  • Cell values: Auto-detected based on content

📝 Formula Examples

Data Processing

=UPPER(A1) & " - " & LOWER(B1)           → Combine formatted strings
=IF(LEN(A1)>0, A1, "Empty")              → Check for non-empty strings
=LEFT(A1, FIND(" ", A1)-1)               → Extract first word
=MID(A1, FIND(" ", A1)+1, LEN(A1))      → Extract everything after first space

Data Validation

=IF(AND(LEN(A1)>3, A1<>""), "Valid", "Invalid")  → Validate string length
=IF(OR(A1="", A1="N/A"), "Missing", A1)          → Handle missing data

Complex Calculations

=SUM(A1:A10) & " total items"            → Numeric result with description
=IF(AVERAGE(A1:A10)>50, "PASS", "FAIL")  → Grade based on average
=CONCAT("Hello ", A1, ", you scored ", B1, "%")  → Dynamic messages

⚠️ Important Notes

  • String Indexing: All string functions use 0-based indexing (FIND, MID, etc.)
  • Case Sensitivity: String comparisons are case-sensitive
  • Error Handling: Invalid operations return #ERROR
  • Empty Strings: "" is considered different from empty cells
  • Quotes in Strings: Use double quotes to escape: "Quote""Test" → Quote"Test

⌨️ Keyboard Shortcuts

Navigation

  • Arrow Keys / hjkl: Move cell selection
  • Page Up/Down: Fast scrolling
  • Home: Jump to cell A1

Editing

  • Enter / F2: Start editing current cell
  • Esc: Cancel editing
  • Enter: Confirm editing

File Operations

  • Ctrl+S: Save in place (Save As if no filename yet)
  • Ctrl+O: Load spreadsheet (prompts if dirty)
  • Ctrl+L: Import CSV (prompts if dirty)
  • Ctrl+E: Export CSV
  • q: Quit (prompts if dirty)
  • Command line: tshts foo.tshts opens at startup

Search & Replace

  • /: Live search; n / N for next / previous
  • Ctrl+R: Find and replace (was Ctrl+H — Ctrl+H is Backspace in many terminals)
  • :regex on, :case on: search-option toggles

View

  • F1 / ?: Show/hide help
  • =: Auto-resize current column
  • +: Auto-resize all columns
  • - / _: Manually adjust column width

🔧 Configuration

TSHTS uses sensible defaults but can be customized:

Default Settings

  • Grid Size: 100 rows × 26 columns
  • Column Width: 8 characters (auto-adjusting)
  • File Format: JSON (.tshts extension)
  • Default Filename: spreadsheet.tshts

File Format

TSHTS saves files in a clean JSON format that's both human-readable and version-control friendly:

{
  "cells": [
    [0, 0, {"value": "Hello", "formula": null}],
    [1, 1, {"value": "42", "formula": "=6*7"}]
  ],
  "rows": 100,
  "cols": 26,
  "column_widths": {"0": 15},
  "default_column_width": 8
}

🏗️ Architecture

TSHTS follows clean architecture and domain-driven design principles:

src/
├── domain/          # Core business logic (no external dependencies)
│   ├── models.rs    # Data structures (Spreadsheet, CellData)
│   ├── services.rs  # Formula evaluation engine and CSV operations
│   └── parser.rs    # Expression parser with formal BNF grammar
├── application/     # Application orchestration
│   └── state.rs     # App state, modes, and business workflows
├── infrastructure/  # External integrations
│   └── persistence.rs # File I/O operations and serialization
├── presentation/    # User interface layer
│   ├── ui.rs        # Terminal rendering with ratatui
│   └── input.rs     # Keyboard input handling and event processing
├── lib.rs           # Library interface
└── main.rs          # Application entry point

Design Benefits

This modular architecture provides:

  • Testable: Each layer has comprehensive unit and integration tests
  • Maintainable: Clear separation of concerns with well-defined interfaces
  • Extensible: Easy to add new functions, operators, and features
  • Portable: Domain logic is UI-framework independent
  • Type-Safe: Leverages Rust's type system for reliability
  • Documentation: Extensive rustdoc comments throughout the codebase

🧪 Testing

TSHTS has comprehensive test coverage:

# Run all tests
cargo test

# Run with coverage
cargo test --release

# Run specific test modules
cargo test domain::
cargo test formula_evaluator

Test categories:

  • Unit Tests: Individual component functionality
  • Integration Tests: File I/O and persistence
  • Formula Tests: Expression evaluation correctness
  • UI Tests: Application state management

📋 System Requirements

  • Operating System: Linux, macOS, Windows (anywhere Rust runs)
  • Terminal: Any terminal with ANSI color and cursor support
  • Rust: 1.70+ with 2024 edition support (for building from source)
  • Memory: Minimal footprint (~10MB typical usage)
  • Storage: Lightweight JSON files (typically <1MB for large sheets)
  • Dependencies: Pure Rust implementation with minimal external dependencies

🤝 Getting Help

  • In-App Help: Press F1 or ? for comprehensive help with scrollable documentation
  • Issues: GitHub Issues
  • Discussions: GitHub Discussions
  • Documentation: This README and extensive rustdoc documentation (cargo doc --open)
  • Examples: Sample .tshts files and formula examples in the repository

📜 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with:

  • Ratatui - Terminal UI framework
  • Crossterm - Cross-platform terminal manipulation
  • Serde - Serialization framework

Special thanks to the Rust community for creating an ecosystem that makes building fast, reliable terminal applications a joy.

Ready to supercharge your terminal workflow? Give TSHTS a try and experience the power of spreadsheets without leaving your command line!

About

A fast, lightweight terminal-based spreadsheet application built in Rust with full formula support, cell references, and keyboard-driven navigation - perfect for command-line workflows.

Resources

Readme

License

MIT license
Activity

Stars

42 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages