334 lines
9.5 KiB
Markdown
334 lines
9.5 KiB
Markdown
# kfmtbox 🌸
|
|
|
|
> A beautiful Rust CLI tool that wraps your text in elegant flower box comments
|
|
|
|
[](https://crates.io/crates/kfmtbox)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://github.com/koftwentytwo/kfmtbox/actions)
|
|
|
|
Transform your plain text into beautiful, decorative comment boxes that automatically adapt to your programming language's comment syntax.
|
|
|
|
## ✨ Features
|
|
|
|
- 🎨 **Beautiful Unicode box drawing** with perfect rectangular formatting
|
|
- 🔍 **Smart file type detection** from filename or explicit specification
|
|
- 📝 **Intelligent text wrapping** with balanced line lengths
|
|
- 🔄 **Existing comment detection** - reformats existing flower boxes
|
|
- ⚙️ **YAML configuration** for custom comment styles
|
|
- 🚀 **Editor integration** ready for Neovim, VSCode, and more
|
|
- 🦀 **Written in Rust** - fast, reliable, and memory-safe
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Installation
|
|
|
|
#### 🚀 One-Line Install (Recommended)
|
|
```bash
|
|
# Linux/macOS
|
|
curl -sSL https://raw.githubusercontent.com/koftwentytwo/kfmtbox/main/install.sh | bash
|
|
|
|
# Windows PowerShell
|
|
powershell -ExecutionPolicy Bypass -File <(curl -sSL https://raw.githubusercontent.com/koftwentytwo/kfmtbox/main/install.ps1)
|
|
```
|
|
|
|
#### 📦 Package Managers
|
|
|
|
**Homebrew (macOS/Linux)**
|
|
```bash
|
|
# Add the tap (after first release)
|
|
brew tap koftwentytwo/kfmtbox
|
|
brew install kfmtbox
|
|
|
|
# Or install directly from formula
|
|
brew install koftwentytwo/kfmtbox/kfmtbox
|
|
```
|
|
|
|
**Cargo (Rust)**
|
|
```bash
|
|
cargo install kfmtbox
|
|
```
|
|
|
|
**Arch Linux (AUR)**
|
|
```bash
|
|
# After AUR package is created
|
|
yay -S kfmtbox
|
|
```
|
|
|
|
#### 🔨 From Source
|
|
```bash
|
|
git clone https://github.com/koftwentytwo/kfmtbox.git
|
|
cd kfmtbox
|
|
cargo build --release
|
|
sudo cp target/release/kfmtbox /usr/local/bin/
|
|
```
|
|
|
|
#### 📥 Manual Download
|
|
Visit the [Releases](https://github.com/koftwentytwo/kfmtbox/releases) page to download pre-built binaries for your platform.
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
echo "Hello, world!" | kfmtbox --filetype rs
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
// ╭───────────────╮
|
|
// │Hello, world! │
|
|
// ╰───────────────╯
|
|
```
|
|
|
|
## 📖 Examples
|
|
|
|
### Different Programming Languages
|
|
|
|
```bash
|
|
# Rust
|
|
echo "Important note" | kfmtbox --filetype rs
|
|
|
|
# Python
|
|
echo "TODO: Fix this bug" | kfmtbox --filetype py
|
|
|
|
# JavaScript
|
|
echo "This function does magic" | kfmtbox --filetype js
|
|
|
|
# SQL
|
|
echo "Complex query explanation" | kfmtbox --filetype sql
|
|
```
|
|
|
|
### Text Wrapping
|
|
|
|
```bash
|
|
# Long text automatically wraps and balances
|
|
echo "This is a very long comment that will be automatically wrapped into multiple lines with balanced spacing" | kfmtbox --filetype py --max-width 40
|
|
```
|
|
|
|
### Reformatting Existing Comments
|
|
|
|
```bash
|
|
# Reformat existing flower boxes
|
|
echo "// ╭─────╮
|
|
// │Old │
|
|
// ╰─────╯" | kfmtbox --filename test.rs
|
|
```
|
|
|
|
## 🛠️ Command Line Options
|
|
|
|
| Option | Description | Example |
|
|
|-------------------|---------------------------------------|----------------------|
|
|
| `-f, --filename` | Detect file type from filename | `--filename main.rs` |
|
|
| `-t, --filetype` | Specify file type explicitly | `--filetype py` |
|
|
| `-w, --max-width` | Set maximum line width (default: 120) | `--max-width 80` |
|
|
| `-h, --help` | Show help information | `--help` |
|
|
| `-V, --version` | Show version information | `--version` |
|
|
|
|
## ⚙️ Configuration
|
|
|
|
Create a YAML configuration file to customize comment styles:
|
|
|
|
**macOS:** `~/Library/Application Support/kfmtbox/comments.yaml`
|
|
**Linux:** `~/.config/kfmtbox/comments.yaml`
|
|
**Windows:** `%APPDATA%\kfmtbox\comments.yaml`
|
|
|
|
```yaml
|
|
comment_styles:
|
|
# Standard languages
|
|
rust: "//"
|
|
python: "#"
|
|
javascript: "//"
|
|
typescript: "//"
|
|
go: "//"
|
|
java: "//"
|
|
cpp: "//"
|
|
c: "//"
|
|
php: "//"
|
|
ruby: "#"
|
|
shell: "#"
|
|
vim: "\""
|
|
lua: "--"
|
|
sql: "--"
|
|
yaml: "#"
|
|
toml: "#"
|
|
ini: ";"
|
|
dockerfile: "#"
|
|
makefile: "#"
|
|
cmake: "#"
|
|
|
|
# Custom file types
|
|
custom: "%%"
|
|
special: "!!"
|
|
```
|
|
|
|
## 🎯 Supported File Types
|
|
|
|
| Language | Extensions | Comment Style |
|
|
|----------------|---------------------------------|---------------|
|
|
| **Rust** | `.rs` | `//` |
|
|
| **Python** | `.py` | `#` |
|
|
| **JavaScript** | `.js` | `//` |
|
|
| **TypeScript** | `.ts` | `//` |
|
|
| **Go** | `.go` | `//` |
|
|
| **Java** | `.java` | `//` |
|
|
| **C/C++** | `.c`, `.cpp`, `.h`, `.hpp` | `//` |
|
|
| **C#** | `.cs` | `//` |
|
|
| **PHP** | `.php` | `//` |
|
|
| **Ruby** | `.rb` | `#` |
|
|
| **Shell** | `.sh`, `.bash`, `.zsh`, `.fish` | `#` |
|
|
| **Vim** | `.vim` | `"` |
|
|
| **Lua** | `.lua` | `--` |
|
|
| **SQL** | `.sql` | `--` |
|
|
| **YAML** | `.yaml`, `.yml` | `#` |
|
|
| **TOML** | `.toml` | `#` |
|
|
| **INI** | `.ini`, `.cfg` | `;` |
|
|
| **Dockerfile** | `Dockerfile` | `#` |
|
|
| **Makefile** | `Makefile` | `#` |
|
|
| **CMake** | `CMakeLists.txt` | `#` |
|
|
|
|
## 🔌 Editor Integration
|
|
|
|
### Neovim
|
|
|
|
Add to your `init.vim` or `init.lua`:
|
|
|
|
```vim
|
|
" Format selected text as flower box
|
|
vnoremap <leader>fb :!kfmtbox --filename %<CR>
|
|
|
|
" Language-specific shortcuts
|
|
vnoremap <leader>fr :!kfmtbox --filetype rs<CR>
|
|
vnoremap <leader>fp :!kfmtbox --filetype py<CR>
|
|
vnoremap <leader>fj :!kfmtbox --filetype js<CR>
|
|
```
|
|
|
|
### VSCode
|
|
|
|
Create a custom task in `.vscode/tasks.json`:
|
|
|
|
```json
|
|
{
|
|
"version": "2.0.0",
|
|
"tasks": [
|
|
{
|
|
"label": "Format as Flower Box",
|
|
"type": "shell",
|
|
"command": "kfmtbox",
|
|
"args": ["--filename", "${file}"],
|
|
"group": "build"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Emacs
|
|
|
|
Add to your `.emacs` or `init.el`:
|
|
|
|
```elisp
|
|
(defun kfmtbox-format-region ()
|
|
"Format selected region as flower box"
|
|
(interactive)
|
|
(shell-command-on-region (region-beginning) (region-end)
|
|
(format "kfmtbox --filename %s" (buffer-file-name))
|
|
nil t))
|
|
|
|
(global-set-key (kbd "C-c f b") 'kfmtbox-format-region)
|
|
```
|
|
|
|
## 🧪 Development
|
|
|
|
### Prerequisites
|
|
|
|
- Rust 1.70+ (edition 2021)
|
|
- Cargo
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/yourusername/kfmtbox.git
|
|
cd kfmtbox
|
|
|
|
# Build in debug mode
|
|
cargo build
|
|
|
|
# Build optimized release
|
|
cargo build --release
|
|
|
|
# Run tests
|
|
cargo test
|
|
|
|
# Check code quality
|
|
cargo clippy
|
|
|
|
# Format code
|
|
cargo fmt
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
kfmtbox/
|
|
├── src/
|
|
│ ├── main.rs # CLI entry point
|
|
│ ├── lib.rs # Library exports
|
|
│ ├── cli.rs # Command line argument parsing
|
|
│ ├── box_renderer.rs # Flower box rendering logic
|
|
│ ├── text_wrapper.rs # Text wrapping and balancing
|
|
│ ├── comment_detector.rs # File type and comment style detection
|
|
│ └── config.rs # YAML configuration handling
|
|
├── Cargo.toml # Project dependencies and metadata
|
|
├── README.md # This file
|
|
├── LICENSE # MIT License
|
|
└── .github/ # GitHub workflows and templates
|
|
```
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
|
|
|
### Quick Contribution Steps
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Make your changes
|
|
4. Add tests for new functionality
|
|
5. Run the test suite (`cargo test`)
|
|
6. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
7. Push to your branch (`git push origin feature/amazing-feature`)
|
|
8. Open a Pull Request
|
|
|
|
## 📋 Roadmap
|
|
|
|
- [ ] **Block comment support** for languages like C/C++ (`/* */`)
|
|
- [ ] **Theming system** with different border styles
|
|
- [ ] **VSCode extension** for seamless integration
|
|
- [ ] **JetBrains plugin** for IntelliJ, PyCharm, etc.
|
|
- [ ] **Auto-detection** of file type from stdin context
|
|
- [ ] **Configurable padding** and border characters
|
|
- [ ] **Multi-line input** with automatic paragraph detection
|
|
|
|
## 🐛 Bug Reports & Feature Requests
|
|
|
|
Found a bug or have an idea? We'd love to hear from you!
|
|
|
|
- 🐛 [Report a bug](https://github.com/yourusername/kfmtbox/issues/new?template=bug_report.md)
|
|
- 💡 [Request a feature](https://github.com/yourusername/kfmtbox/issues/new?template=feature_request.md)
|
|
- 💬 [Start a discussion](https://github.com/yourusername/kfmtbox/discussions)
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- Inspired by the need for beautiful, consistent comment formatting
|
|
- Built with ❤️ using [Rust](https://www.rust-lang.org/)
|
|
- Uses [clap](https://github.com/clap-rs/clap) for CLI parsing
|
|
- Configuration powered by [serde_yaml](https://github.com/dtolnay/serde-yaml)
|
|
|
|
---
|
|
|
|
**Made with ❤️ by the kfmtbox team**
|
|
|
|
[⭐ Star this repo](https://github.com/yourusername/kfmtbox) if you find it useful!
|