298 lines
6.8 KiB
Markdown
298 lines
6.8 KiB
Markdown
# JQuote.nvim
|
|
|
|
A powerful Neovim plugin for cycling through quote characters with intelligent auto-jump functionality.
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://lua.org)
|
|
[](https://neovim.io)
|
|
|
|
## ✨ Features
|
|
|
|
- **🔄 Quote Cycling**: Seamlessly cycle through different quote characters (`'`, `"`, `` ` ``)
|
|
- **🎯 Auto Jump**: Automatically jump to the next quote pair when cursor is not inside quotes
|
|
- **⚙️ Configurable**: Customize quote characters, hotkeys, and jump behavior
|
|
- **🛡️ Enterprise-Grade**: Comprehensive error handling and defensive programming
|
|
- **📊 Health Monitoring**: Built-in health check and diagnostics
|
|
- **🏗️ Version Management**: Dynamic version detection from git tags
|
|
- **🧪 Thoroughly Tested**: Comprehensive unit test suite with 25+ test cases
|
|
|
|
## 📋 Requirements
|
|
|
|
- Neovim 0.5.0 or later
|
|
- Lua 5.1+
|
|
|
|
## 📦 Installation
|
|
|
|
### Using [lazy.nvim](https://github.com/folke/lazy.nvim)
|
|
|
|
```lua
|
|
{
|
|
"your-username/jquote.nvim",
|
|
config = function()
|
|
require("jquote").setup({
|
|
-- Optional configuration
|
|
hotkey = "<leader>tq",
|
|
quote_chars = { "'", '"', "`" },
|
|
jump_behavior = "auto"
|
|
})
|
|
end,
|
|
}
|
|
```
|
|
|
|
### Using [packer.nvim](https://github.com/wbthomason/packer.nvim)
|
|
|
|
```lua
|
|
use {
|
|
"your-username/jquote.nvim",
|
|
config = function()
|
|
require("jquote").setup()
|
|
end
|
|
}
|
|
```
|
|
|
|
### Using [vim-plug](https://github.com/junegunn/vim-plug)
|
|
|
|
```vim
|
|
Plug 'your-username/jquote.nvim'
|
|
|
|
lua << EOF
|
|
require("jquote").setup()
|
|
EOF
|
|
```
|
|
|
|
### Manual Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/your-username/jquote.nvim.git ~/.config/nvim/lua/jquote
|
|
|
|
# Or use the Makefile
|
|
make install
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### Default Configuration
|
|
|
|
```lua
|
|
require("jquote").setup({
|
|
hotkey = "<leader>tq", -- Key binding for quote toggle
|
|
quote_chars = { "'", '"', "`" }, -- Quote characters to cycle through
|
|
jump_behavior = "auto" -- "auto" or "manual" jump behavior
|
|
})
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `hotkey` | `string` | `"<leader>tq"` | Key mapping for toggling quotes |
|
|
| `quote_chars` | `table` | `{ "'", '"', "`" }` | List of quote characters to cycle through |
|
|
| `jump_behavior` | `string` | `"auto"` | Jump behavior when cursor is not in quotes (`"auto"` or `"manual"`) |
|
|
|
|
### Custom Configuration Examples
|
|
|
|
```lua
|
|
-- Minimal setup with custom hotkey
|
|
require("jquote").setup({
|
|
hotkey = "<leader>q"
|
|
})
|
|
|
|
-- Custom quote characters
|
|
require("jquote").setup({
|
|
quote_chars = { "'", '"' } -- Only single and double quotes
|
|
})
|
|
|
|
-- Manual jump behavior
|
|
require("jquote").setup({
|
|
jump_behavior = "manual" -- Don't auto-jump, only toggle quotes at cursor
|
|
})
|
|
|
|
-- Full customization
|
|
require("jquote").setup({
|
|
hotkey = "<C-q>",
|
|
quote_chars = { "'", '"', "`", "«", "»" }, -- Including Unicode quotes
|
|
jump_behavior = "auto"
|
|
})
|
|
```
|
|
|
|
## 🚀 Usage
|
|
|
|
### Basic Usage
|
|
|
|
1. **Toggle Quotes**: Place your cursor inside or on a quoted string and press `<leader>tq` (or your configured hotkey)
|
|
2. **Auto Jump**: When cursor is not inside quotes, the plugin automatically jumps to the next quote pair forward
|
|
|
|
### Examples
|
|
|
|
```lua
|
|
-- Before: cursor anywhere in 'hello world'
|
|
'hello world'
|
|
|
|
-- After pressing <leader>tq
|
|
"hello world"
|
|
|
|
-- After pressing <leader>tq again
|
|
`hello world`
|
|
|
|
-- After pressing <leader>tq again (cycles back)
|
|
'hello world'
|
|
```
|
|
|
|
### Auto Jump Feature
|
|
|
|
```lua
|
|
-- Before: cursor at beginning of line
|
|
hello 'world' and "test"
|
|
^
|
|
|
|
-- After pressing <leader>tq (auto-jumps to first quote)
|
|
hello 'world' and "test"
|
|
^
|
|
-- And toggles the quotes
|
|
hello "world" and "test"
|
|
```
|
|
|
|
### Multiple Quote Pairs
|
|
|
|
```lua
|
|
-- Works with multiple quote pairs on the same line
|
|
print('Hello', "World", `Template`)
|
|
|
|
-- Handles nested quotes intelligently
|
|
outer "inner 'nested' text" end
|
|
```
|
|
|
|
## 🔧 Commands and Functions
|
|
|
|
### Available Functions
|
|
|
|
```lua
|
|
local jquote = require("jquote")
|
|
|
|
-- Setup the plugin
|
|
jquote.setup(options)
|
|
|
|
-- Toggle quotes at cursor position
|
|
jquote.toggle_quotes()
|
|
|
|
-- Get current plugin version
|
|
local version = jquote.get_version()
|
|
|
|
-- Get plugin health information
|
|
local health = jquote.health()
|
|
```
|
|
|
|
### Health Check
|
|
|
|
Check plugin status and configuration:
|
|
|
|
```lua
|
|
:lua print(vim.inspect(require("jquote").health()))
|
|
```
|
|
|
|
Output example:
|
|
```lua
|
|
{
|
|
hotkey_configured = true,
|
|
jump_behavior_valid = true,
|
|
options = { ... },
|
|
plugin_version = "1.2.0",
|
|
quote_chars_count = 3
|
|
}
|
|
```
|
|
|
|
## 🧪 Development
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
make test
|
|
|
|
# Check syntax
|
|
make check
|
|
|
|
# Run development checks (syntax + tests)
|
|
make dev-check
|
|
|
|
# Quick development workflow
|
|
make quick
|
|
```
|
|
|
|
### Test Coverage
|
|
|
|
The plugin includes comprehensive unit tests covering:
|
|
|
|
- ✅ Plugin initialization and configuration
|
|
- ✅ Quote detection and cycling
|
|
- ✅ Auto jump functionality
|
|
- ✅ Error handling and edge cases
|
|
- ✅ Version management
|
|
- ✅ Health monitoring
|
|
- ✅ Boundary conditions and defensive programming
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
jquote.nvim/
|
|
├── lua/
|
|
│ └── jquote/
|
|
│ └── init.lua # Main plugin code
|
|
├── tests/
|
|
│ ├── init_spec.lua # Comprehensive test suite
|
|
│ ├── test_runner.lua # Custom test framework
|
|
│ └── README.md # Testing documentation
|
|
├── Makefile # Development workflow
|
|
└── README.md # This file
|
|
```
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions are welcome! Please ensure:
|
|
|
|
1. **Code Quality**: Follow the established corporate clean code standards
|
|
2. **Testing**: Add tests for new features and ensure all tests pass
|
|
3. **Documentation**: Update documentation for any new features or changes
|
|
|
|
### Development Workflow
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/your-username/jquote.nvim.git
|
|
cd jquote.nvim
|
|
|
|
# Run tests
|
|
make test
|
|
|
|
# Check code quality
|
|
make check
|
|
|
|
# Install for local development
|
|
make install
|
|
```
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- Inspired by the need for efficient quote management in Neovim
|
|
- Built with enterprise-grade reliability and comprehensive testing
|
|
- Designed for developer productivity and workflow optimization
|
|
|
|
## 📞 Support
|
|
|
|
If you encounter any issues or have suggestions:
|
|
|
|
1. Check the [Issues](https://git.kjan.de/jank/jquote.nvim/issues) page
|
|
2. Run the health check: `:lua print(vim.inspect(require("jquote").health()))`
|
|
3. Create a new issue with:
|
|
- Your configuration
|
|
- Health check output
|
|
- Steps to reproduce the problem
|
|
|
|
---
|
|
|
|
**Made with ❤️ for the Neovim community**
|